@visual-z/xeno 0.2.1 → 0.4.0

package/src/tui/ui/edge.ts

@@ -0,0 +1,186 @@
+/**
+ * Labels set into a one-row rule (docs/tasks/refactor-tui-dock-layout.md). Pure.
+ *
+ *     ╭─ left · left ───────────────── right ─╮     the input box edges
+ *     ── node 3 · model switch ───────────────      transcript dividers
+ *     xeno  title                 right   right     the top bar (splitLine)
+ *
+ * A row never wraps and never squeezes what is next to it, so when labels do
+ * not fit, the least important go first: each label has a priority (0 is
+ * never dropped), and a label with `min` shrinks to that many cells with an
+ * ellipsis before it is dropped. The output is always exactly `width` cells,
+ * measured with the same display width the renderer uses (CJK counts 2).
+ */
+import { displayWidth } from "../width.ts";
+
+/** Colour roles; the view maps them to the current palette. */
+export type Role = "text" | "muted" | "edge" | "line" | "accent" | "success" | "error" | "warning" | "reasoning" | "code";
+
+export interface Seg {
+  readonly text: string;
+  readonly role: Role;
+  readonly bold?: boolean;
+  readonly italic?: boolean;
+  /** Drawn with the activity clock's current glyph instead of `text` (one cell). */
+  readonly spin?: boolean;
+}
+
+export interface Label {
+  readonly segs: readonly Seg[];
+  /** 0 is never dropped; among the rest, higher numbers drop first. */
+  readonly priority: number;
+  /** Shrink the `shrink` seg (default 0) to this many cells before dropping. */
+  readonly min?: number;
+  readonly shrink?: number;
+  /**
+   * When to shrink, on the same scale as `priority` (default: the label's own
+   * priority). A never-dropped title can still give up width early.
+   */
+  readonly shrinkPriority?: number;
+}
+
+export const SEPARATOR: readonly Seg[] = [{ text: " · ", role: "muted" }];
+
+function segWidth(seg: Seg): number { return seg.spin ? 1 : displayWidth(seg.text); }
+
+export function segsWidth(segs: readonly Seg[]): number {
+  let width = 0;
+  for (const seg of segs) width += segWidth(seg);
+  return width;
+}
+
+/** Cut `text` to at most `width` cells, ending in "…" when anything was cut. */
+export function clipText(text: string, width: number): string {
+  if (width <= 0) return "";
+  if (displayWidth(text) <= width) return text;
+  let out = "", used = 0;
+  for (const ch of text) {
+    const w = displayWidth(ch);
+    if (used + w > width - 1) break;
+    out += ch; used += w;
+  }
+  return `${out}…`;
+}
+
+/** Cut a run of segs to at most `width` cells; the cut seg ends in "…". */
+export function clipSegs(segs: readonly Seg[], width: number): Seg[] {
+  if (segsWidth(segs) <= width) return [...segs];
+  const out: Seg[] = [];
+  let left = width;
+  for (let i = 0; i < segs.length; i++) {
+    const seg = segs[i]!, w = segWidth(seg);
+    if (w < left) { out.push(seg); left -= w; continue; }
+    if (left <= 0) break;
+    if (!seg.spin) {
+      // Something after this seg is being cut away, so this seg carries the ellipsis.
+      const body = clipText(seg.text, left - 1).replace(/…$/, "");
+      out.push({ ...seg, text: `${body}…` });
+    }
+    break;
+  }
+  return out;
+}
+
+interface Fitted { label: Label; segs: Seg[]; index: number; side: "left" | "right" }
+
+/**
+ * Which labels survive in `avail` cells. Returns the joined segs per side
+ * and the indices kept, so callers and tests can see exactly what dropped.
+ * `gap` is the minimum space between the two sides when both survive.
+ */
+export function fitLabels(avail: number, left: readonly Label[], right: readonly Label[], separator: readonly Seg[] = SEPARATOR, gap = 0):
+  { left: Seg[]; right: Seg[]; keptLeft: number[]; keptRight: number[] } {
+  let items: Fitted[] = [
+    ...left.map((label, index) => ({ label, segs: [...label.segs], index, side: "left" as const })),
+    ...right.map((label, index) => ({ label, segs: [...label.segs], index, side: "right" as const })),
+  ];
+  const sepWidth = segsWidth(separator);
+  const width = () => {
+    let l = 0, r = 0, nl = 0, nr = 0;
+    for (const item of items) { const w = segsWidth(item.segs); if (item.side === "left") { l += w; nl++; } else { r += w; nr++; } }
+    return l + r + Math.max(0, nl - 1) * sepWidth + Math.max(0, nr - 1) * sepWidth + (nl && nr ? gap : 0);
+  };
+  const shrinkable = (item: Fitted) => item.label.min !== undefined && segsWidth(item.segs) > item.label.min;
+  // The step a label takes next and how unimportant that step is: shrinking happens at
+  // `shrinkPriority`, dropping at `priority`. Least important step first; on a tie a
+  // shrink comes before a drop, and the right side (the less central one) before the left.
+  const level = (item: Fitted) => shrinkable(item) ? item.label.shrinkPriority ?? item.label.priority : item.label.priority;
+  const before = (a: Fitted, b: Fitted) => level(a) !== level(b) ? level(a) > level(b)
+    : shrinkable(a) !== shrinkable(b) ? shrinkable(a) : a.side === "right" && b.side === "left";
+  for (let guard = 0; width() > avail && guard < 500; guard++) {
+    const candidates = items.filter(item => item.label.priority > 0 || shrinkable(item));
+    if (!candidates.length) break;
+    const victim = candidates.reduce((a, b) => before(b, a) ? b : a);
+    if (shrinkable(victim)) shrink(victim, Math.max(victim.label.min!, segsWidth(victim.segs) - (width() - avail)));
+    else items = items.filter(item => item !== victim);
+  }
+  // Still too wide: only never-dropped labels at their minimum remain. Cut them, right side first.
+  for (const item of [...items].reverse()) {
+    const over = width() - avail;
+    if (over <= 0) break;
+    shrink(item, Math.max(0, segsWidth(item.segs) - over));
+  }
+  items = items.filter(item => segsWidth(item.segs) > 0);
+  const join = (side: "left" | "right") => {
+    const list = items.filter(item => item.side === side);
+    return { segs: list.flatMap((item, i) => i ? [...separator, ...item.segs] : item.segs), kept: list.map(item => item.index) };
+  };
+  const l = join("left"), r = join("right");
+  return { left: l.segs, right: r.segs, keptLeft: l.kept, keptRight: r.kept };
+}
+
+function shrink(item: Fitted, target: number): void {
+  if (!item.segs.length) return;
+  const at = Math.min(item.label.shrink ?? 0, item.segs.length - 1);
+  const room = target - (segsWidth(item.segs) - segWidth(item.segs[at]!));
+  if (room <= 0 || item.segs[at]!.spin) { item.segs = clipSegs(item.segs, target); return; }
+  item.segs[at] = { ...item.segs[at]!, text: clipText(item.segs[at]!.text, room) };
+  item.segs = item.segs.filter(seg => seg.spin || seg.text.length > 0);
+}
+
+export interface EdgeOptions {
+  readonly width: number;
+  readonly left?: readonly Label[];
+  readonly right?: readonly Label[];
+  /** Corner glyphs; omit for a rule with open ends (transcript dividers). */
+  readonly corners?: readonly [string, string];
+  readonly fill?: string;
+  readonly role?: Role;
+  /** Fill cells before the left labels and after the right ones. Default 1. */
+  readonly lead?: number;
+  readonly trail?: number;
+}
+
+/** One complete row, exactly `width` cells (a wide character cut at the end is filled). */
+export function edgeLine(options: EdgeOptions): Seg[] {
+  const width = Math.max(0, Math.floor(options.width));
+  const role = options.role ?? "edge", fill = options.fill ?? "─", corners = options.corners;
+  if (width === 0) return [];
+  if (corners && width < 2) return [{ text: corners[0], role }];
+  const left = options.left ?? [], right = options.right ?? [];
+  const lead = options.lead ?? 1, trail = options.trail ?? 1;
+  const inner = width - (corners ? 2 : 0);
+  const pads = (left.length ? 2 : 0) + (right.length ? 2 : 0);
+  const fitted = fitLabels(Math.max(0, inner - lead - trail - pads), left, right, SEPARATOR, 1);
+  const out: Seg[] = [];
+  let used = 0;
+  const push = (seg: Seg) => { if (seg.spin || seg.text) { out.push(seg); used += segWidth(seg); } };
+  if (corners) out.push({ text: corners[0], role });
+  push({ text: fill.repeat(Math.min(lead, inner)), role });
+  if (fitted.left.length) { push({ text: " ", role }); fitted.left.forEach(push); push({ text: " ", role }); }
+  const rightBlock = fitted.right.length ? segsWidth(fitted.right) + 2 : 0;
+  const gap = inner - used - rightBlock - trail;
+  if (gap > 0) push({ text: fill.repeat(gap), role });
+  if (fitted.right.length) { push({ text: " ", role }); fitted.right.forEach(push); push({ text: " ", role }); }
+  if (inner - used > 0) push({ text: fill.repeat(inner - used), role });
+  if (corners) out.push({ text: corners[1], role });
+  return out;
+}
+
+/** A row with labels at both ends and blank space between (the top bar). Exactly `width` cells. */
+export function splitLine(width: number, left: readonly Label[], right: readonly Label[], gap = 3, separator: readonly Seg[] = [{ text: "   ", role: "muted" }]): Seg[] {
+  const w = Math.max(0, Math.floor(width));
+  const fitted = fitLabels(w, left, right, separator, gap);
+  const space = w - segsWidth(fitted.left) - segsWidth(fitted.right);
+  return [...fitted.left, ...(space > 0 ? [{ text: " ".repeat(space), role: "text" as const }] : []), ...fitted.right];
+}

package/src/tui/ui/image-size.ts

@@ -0,0 +1,40 @@
+/**
+ * How many terminal cells a picture takes (docs/tasks/feat-tui-inline-images.md). Pure.
+ *
+ * A cell is taller than it is wide, so keeping a picture's shape means
+ * columns / rows = (width / height) × (cell height / cell width). The result
+ * fits the given box, is at least one cell, and never asks for more cells
+ * than the picture has pixels for: a 16-pixel icon stays small instead of
+ * being blown up into a blurry tile.
+ */
+
+export interface CellSize { readonly cols: number; readonly rows: number }
+
+/** Pixels per cell when the terminal does not report them: 9×18, the common default. Assumed. */
+export const DEFAULT_CELL = { width: 9, height: 18 } as const;
+
+export function imageCells(pixels: { readonly width: number; readonly height: number }, maxCols: number, maxRows: number,
+  cell: { readonly width: number; readonly height: number } = DEFAULT_CELL): CellSize {
+  const w = Math.max(1, pixels.width), h = Math.max(1, pixels.height);
+  const cw = cell.width > 0 ? cell.width : DEFAULT_CELL.width, ch = cell.height > 0 ? cell.height : DEFAULT_CELL.height;
+  // The picture's own size in cells caps the box: no upscaling.
+  const capCols = Math.max(1, Math.min(Math.floor(maxCols), Math.ceil(w / cw)));
+  const capRows = Math.max(1, Math.min(Math.floor(maxRows), Math.ceil(h / ch)));
+  const shape = (w / h) * (ch / cw); // columns per row that keep the picture's proportions
+  let rows = capRows, cols = Math.round(rows * shape);
+  if (cols > capCols) { cols = capCols; rows = Math.round(cols / shape); }
+  return { cols: Math.max(1, Math.min(capCols, cols)), rows: Math.max(1, Math.min(capRows, rows)) };
+}
+
+/** Rows for pictures in the transcript: a quarter of the terminal, 4–12. Assumed, between OpenCode (≤8) and Grok (≤20). */
+export function transcriptImageRows(terminalRows: number): number {
+  return Math.max(4, Math.min(12, Math.floor(terminalRows / 4)));
+}
+
+/** Rows for the attachment strip above the input box: a sixth of the terminal, 3–6. Assumed. */
+export function stripImageRows(terminalRows: number): number {
+  return Math.max(3, Math.min(6, Math.floor(terminalRows / 6)));
+}
+
+/** Pictures shown per message before "+N more" (OpenCode shows 3). */
+export const IMAGES_PER_ITEM = 3;

package/src/tui/ui/ink.ts

@@ -0,0 +1,210 @@
+/**
+ * Terminal-owned colour (docs/tasks/refactor-tui-terminal-colors.md). Pure.
+ *
+ * The terminal already has a palette the user chose, often with transparency
+ * and blur behind it. Painting our own background defeats both, and fixed RGB
+ * accents clash with whatever palette is underneath. So the view asks the
+ * terminal (OSC 4/10/11 via OpenTUI) and derives every role from the answer:
+ *
+ *   text        the terminal's own foreground (SGR 39), never a guess
+ *   background  the terminal's own background (SGR 49): nothing is painted
+ *   accents     one of the 16 slots, picked for contrast and hue
+ *   greys       the foreground blended toward the background, as faint as a
+ *               contrast target allows (Codex styles.md does the same)
+ *
+ * When the terminal does not answer, a dark/light hint picks the slots and
+ * fixed greys. Semantic colour still only marks glyphs and rules; it never
+ * colours body text (D11 keeps green/red for logged outcomes).
+ */
+
+/** How a colour is emitted. Indexed and default colours follow the terminal if its palette changes. */
+export type InkSpec =
+  | { readonly kind: "default" }
+  | { readonly kind: "index"; readonly index: number }
+  | { readonly kind: "rgb"; readonly hex: string };
+
+export interface TerminalPalette {
+  readonly foreground: string;
+  readonly background: string;
+  /** The 16 ANSI slots as #rrggbb. */
+  readonly slots: readonly string[];
+  /** The terminal's own selection colours (OSC 17 / 19), when it reports them. */
+  readonly highlight?: { readonly background: string; readonly foreground: string };
+}
+
+export const INK_ROLES = ["text", "muted", "edge", "line", "accent", "success", "error", "warning", "reasoning", "code"] as const;
+export type InkRole = (typeof INK_ROLES)[number];
+export type InkSet = { readonly [K in InkRole]: InkSpec } & {
+  readonly background: InkSpec;
+  /** Selected text: the terminal's selection colours, else an inverse of its own ground (feat-tui-copy-selection DoD 5). */
+  readonly selectionBg: InkSpec;
+  readonly selectionFg: InkSpec;
+}
+
+/**
+ * Contrast targets. 4.5:1 is WCAG AA for text and 3:1 for UI components;
+ * 1.8:1 for decorative rules is an assumption (visible, never louder than text).
+ * A terminal whose own foreground is weaker than these gets proportionally
+ * lower targets, so muted text never becomes louder than body text.
+ */
+const MUTED = { target: 4.5, share: 0.62 };
+const EDGE = { target: 3, share: 0.42 };
+const LINE = { target: 1.8, share: 0.3 };
+/** Minimum contrast for an accent glyph against the background (WCAG non-text). */
+const ACCENT_CONTRAST = 3;
+/** Below this saturation a slot is a grey, not a hue (Solarized's bright slots). Assumed. */
+const CHROMATIC = 0.15;
+/** A bright slot stands in for its normal slot only within this hue distance. Assumed. */
+const SAME_HUE_DEGREES = 40;
+
+/** [normal, bright] slot pairs per role, in preference order. */
+const SLOTS: Readonly<Record<Exclude<InkRole, "text" | "muted" | "edge" | "line">, readonly (readonly [number, number])[]>> = {
+  accent: [[4, 12], [6, 14]],
+  success: [[2, 10]],
+  error: [[1, 9]],
+  warning: [[3, 11]],
+  reasoning: [[5, 13]],
+  code: [[6, 14]],
+};
+
+/** Greys used when the terminal does not report its palette. Chosen for ≥ 4.5 / 3 / 1.6 on typical dark (#1e1e1e) and light (#ffffff) grounds. */
+const FALLBACK_GREYS = {
+  dark: { muted: "#9a9a9a", edge: "#6e6e6e", line: "#4a4a4a" },
+  light: { muted: "#6a6a6a", edge: "#949494", line: "#c8c8c8" },
+} as const;
+
+export function terminalInks(palette: TerminalPalette | null, hint: "dark" | "light"): InkSet {
+  const valid = palette !== null && isHex(palette.foreground) && isHex(palette.background) && palette.slots.length >= 16 && palette.slots.slice(0, 16).every(isHex);
+  if (!valid) return fallbackInks(hint);
+  const { foreground: fg, background: bg } = palette;
+  const dark = luminance(bg) < luminance(fg);
+  const c = contrast(fg, bg);
+  const pick = (pairs: readonly (readonly [number, number])[]): InkSpec => pickSlot(palette.slots, pairs, dark, bg);
+  const highlight = palette.highlight && isHex(palette.highlight.background) && isHex(palette.highlight.foreground) ? palette.highlight : undefined;
+  return {
+    background: { kind: "default" },
+    text: { kind: "default" },
+    selectionBg: { kind: "rgb", hex: highlight?.background ?? fg },
+    selectionFg: { kind: "rgb", hex: highlight?.foreground ?? bg },
+    muted: { kind: "rgb", hex: faintest(fg, bg, Math.min(MUTED.target, MUTED.share * c)) },
+    edge: { kind: "rgb", hex: faintest(fg, bg, Math.min(EDGE.target, EDGE.share * c)) },
+    line: { kind: "rgb", hex: faintest(fg, bg, Math.min(LINE.target, LINE.share * c)) },
+    accent: pick(SLOTS.accent), success: pick(SLOTS.success), error: pick(SLOTS.error),
+    warning: pick(SLOTS.warning), reasoning: pick(SLOTS.reasoning), code: pick(SLOTS.code),
+  };
+}
+
+function fallbackInks(hint: "dark" | "light"): InkSet {
+  const greys = FALLBACK_GREYS[hint];
+  // Without a palette, a bright slot is the safer guess on dark grounds and the normal slot on light ones.
+  const slot = (pair: readonly [number, number]): InkSpec => ({ kind: "index", index: hint === "dark" ? pair[1] : pair[0] });
+  return {
+    background: { kind: "default" }, text: { kind: "default" },
+    // Inverse through the terminal's own black and white slots: its ground colours are unknown here.
+    selectionBg: { kind: "index", index: hint === "dark" ? 15 : 0 }, selectionFg: { kind: "index", index: hint === "dark" ? 0 : 15 },
+    muted: { kind: "rgb", hex: greys.muted }, edge: { kind: "rgb", hex: greys.edge }, line: { kind: "rgb", hex: greys.line },
+    accent: slot(SLOTS.accent[0]!), success: slot(SLOTS.success[0]!), error: slot(SLOTS.error[0]!),
+    warning: slot(SLOTS.warning[0]!), reasoning: slot(SLOTS.reasoning[0]!), code: slot(SLOTS.code[0]!),
+  };
+}
+
+function pickSlot(slots: readonly string[], pairs: readonly (readonly [number, number])[], dark: boolean, bg: string): InkSpec {
+  const candidates: number[] = [];
+  for (const [normal, bright] of pairs) {
+    const normalOk = saturation(slots[normal]!) > CHROMATIC;
+    const brightOk = saturation(slots[bright]!) > CHROMATIC && sameHue(slots[bright]!, slots[normal]!);
+    for (const index of dark ? [bright, normal] : [normal, bright]) if (index === bright ? brightOk : normalOk) candidates.push(index);
+  }
+  const readable = candidates.find(index => contrast(slots[index]!, bg) >= ACCENT_CONTRAST);
+  if (readable !== undefined) return { kind: "index", index: readable };
+  // Every candidate is too faint on this ground: keep the first hue, pushed away from the background.
+  if (candidates.length) return { kind: "rgb", hex: deepen(slots[candidates[0]!]!, bg, ACCENT_CONTRAST) };
+  // No chromatic slot at all (a monochrome palette): the terminal's own slot is still the honest choice.
+  return { kind: "index", index: pairs[0]![0] };
+}
+
+// ----------------------------------------------------------------- colour math
+
+export function isHex(value: string): boolean { return /^#[0-9a-fA-F]{6}$/.test(value); }
+
+function channels(hex: string): [number, number, number] {
+  const n = Number.parseInt(hex.slice(1), 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+function toHex(values: readonly number[]): string {
+  return `#${values.map(v => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, "0")).join("")}`;
+}
+
+/** WCAG relative luminance. */
+export function luminance(hex: string): number {
+  const linear = (v: number) => { const s = v / 255; return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; };
+  const [r, g, b] = channels(hex);
+  return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+
+/** WCAG contrast ratio, 1–21. */
+export function contrast(a: string, b: string): number {
+  const x = luminance(a), y = luminance(b);
+  return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05);
+}
+
+/** `share` of `from` over `to` (1 = from, 0 = to). */
+export function mix(from: string, to: string, share: number): string {
+  const a = channels(from), b = channels(to);
+  return toHex(a.map((v, i) => b[i]! + (v - b[i]!) * share));
+}
+
+export function saturation(hex: string): number {
+  const values = channels(hex).map(v => v / 255);
+  const max = Math.max(...values), min = Math.min(...values);
+  return max === 0 ? 0 : (max - min) / max;
+}
+
+export function hue(hex: string): number {
+  const [r, g, b] = channels(hex).map(v => v / 255) as [number, number, number];
+  const max = Math.max(r, g, b), min = Math.min(r, g, b), d = max - min;
+  if (d === 0) return 0;
+  const sector = max === r ? ((g - b) / d) % 6 : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
+  return (sector * 60 + 360) % 360;
+}
+
+export function sameHue(a: string, b: string): boolean {
+  const d = Math.abs(hue(a) - hue(b));
+  return Math.min(d, 360 - d) <= SAME_HUE_DEGREES;
+}
+
+/**
+ * The blend of fg into bg closest to bg that still reaches `target` against
+ * bg, in 1% steps. Never louder than fg itself: a channel-wise blend is not
+ * monotone in luminance when fg and bg differ in hue, so an intermediate mix
+ * can out-contrast fg, and a grey must not compete with body text.
+ */
+export function faintest(fg: string, bg: string, target: number): string {
+  const ceiling = contrast(fg, bg);
+  if (ceiling <= target) return fg;
+  for (let step = 1; step <= 100; step++) {
+    const color = mix(fg, bg, step / 100);
+    const c = contrast(color, bg);
+    if (c >= target) return c <= ceiling ? color : fg;
+  }
+  return fg;
+}
+
+/**
+ * Push a colour toward white (dark ground) or black (light ground) until it
+ * reaches `target` against bg, in 5% steps. Mixing with white or black
+ * preserves hue exactly, and luminance moves monotonically away from bg, so
+ * a too-faint yellow becomes a darker yellow rather than some other colour.
+ * Either extreme reaches at least 4.58:1 against any ground, so any target up
+ * to that is always met.
+ */
+export function deepen(color: string, bg: string, target: number): string {
+  if (contrast(color, bg) >= target) return color;
+  const extreme = contrast("#ffffff", bg) >= contrast("#000000", bg) ? "#ffffff" : "#000000";
+  for (let step = 1; step <= 20; step++) {
+    const next = mix(extreme, color, step / 20);
+    if (contrast(next, bg) >= target) return next;
+  }
+  return extreme;
+}

package/src/tui/ui/items.ts

@@ -0,0 +1,40 @@
+/**
+ * What the message stream shows, as plain data. The app projects its log
+ * into these (apps/ui/project.ts); the view never sees log events.
+ *
+ * `rev` changes whenever an item's content changes; equal id + rev means the
+ * renderable can be reused untouched, which keeps long sessions cheap.
+ */
+export type ToolStatus = "pending" | "ok" | "error";
+
+/** A picture the view may draw: its blob address, name and pixel size (from the log's ImageRef). */
+export interface ImageView { readonly sha256: string; readonly name: string; readonly width: number; readonly height: number }
+
+export type ViewItem =
+  | { readonly kind: "user"; readonly id: string; readonly rev: string; readonly text: string; readonly images?: readonly ImageView[]; readonly interrupted?: boolean }
+  | { readonly kind: "assistant"; readonly id: string; readonly rev: string; readonly text: string; readonly streaming?: boolean }
+  | { readonly kind: "thinking"; readonly id: string; readonly rev: string; readonly text: string; readonly streaming?: boolean; readonly label?: string }
+  | { readonly kind: "tool"; readonly id: string; readonly rev: string; readonly name: string; readonly summary: string; readonly status: ToolStatus;
+      /** Evidence shown right-aligned: "exit 0", "+3 −1", "12 lines". Never the model's own claim (D11). */
+      readonly evidence?: string; readonly preview?: readonly string[]; readonly images?: readonly ImageView[]; readonly detail: (width: number) => string[] }
+  | { readonly kind: "notice"; readonly id: string; readonly rev: string; readonly text: string; readonly tone?: "info" | "success" | "warning" | "error" }
+  | { readonly kind: "segment"; readonly id: string; readonly rev: string; readonly label: string; readonly detail?: string }
+  | { readonly kind: "lines"; readonly id: string; readonly rev: string; readonly render: (width: number) => string[] };
+
+/**
+ * Pure: what the reader missed between two projections. `added` counts
+ * items that did not exist before (a streaming reply growing is one
+ * message, not one per delta); `changed` says whether anything already
+ * shown changed. The session-start rule is chrome and never counts.
+ */
+export function unseen(previous: readonly ViewItem[], next: readonly ViewItem[]): { added: number; changed: boolean } {
+  const before = new Map(previous.map(item => [item.id, item.rev]));
+  let added = 0, changed = false;
+  for (const item of next) {
+    if (item.id === "session-start") continue;
+    const rev = before.get(item.id);
+    if (rev === undefined) added++;
+    else if (rev !== item.rev) changed = true;
+  }
+  return { added, changed };
+}

package/src/tui/ui/keys.ts

@@ -0,0 +1,40 @@
+/**
+ * One key shape for the whole view. OpenTUI's KeyEvent is normalised into a
+ * chord string in core/keymap's canonical order (ctrl+alt+shift+super+key)
+ * so bindings parsed from settings compare by string equality.
+ */
+import type { KeyEvent } from "@opentui/core";
+
+export interface KeyPress {
+  readonly chord: string;
+  readonly name: string;
+  readonly ctrl: boolean;
+  readonly alt: boolean;
+  readonly shift: boolean;
+  /** Printable text this key inserts, or "" for a control key. */
+  readonly text: string;
+}
+
+const RENAME: Readonly<Record<string, string>> = { return: "enter", esc: "escape", " ": "space" };
+
+export function keyPress(event: Pick<KeyEvent, "name" | "ctrl" | "meta" | "shift" | "sequence"> & { option?: boolean; super?: boolean }): KeyPress {
+  const raw = (event.name || "").toLowerCase();
+  const name = RENAME[raw] ?? raw;
+  const alt = Boolean(event.meta || event.option);
+  const sup = Boolean(event.super);
+  const printable = !event.ctrl && !alt && !sup && typeof event.sequence === "string" && event.sequence.length > 0 && !/[\x00-\x1f\x7f]/.test(event.sequence) && !event.sequence.startsWith("\x1b");
+  const parts: string[] = [];
+  if (event.ctrl) parts.push("ctrl");
+  if (alt) parts.push("alt");
+  // Shift on a printable character is already in the character itself.
+  if (event.shift && !(printable && name.length === 1)) parts.push("shift");
+  if (sup) parts.push("super");
+  parts.push(name);
+  return { chord: parts.join("+"), name, ctrl: Boolean(event.ctrl), alt, shift: Boolean(event.shift), text: printable ? event.sequence : "" };
+}
+
+export type Bindings = Readonly<Record<string, readonly string[]>>;
+
+export function bound(bindings: Bindings, action: string, key: KeyPress): boolean {
+  return (bindings[action] ?? []).includes(key.chord);
+}

package/src/tui/ui/layout.ts

@@ -0,0 +1,74 @@
+/**
+ * Where status lives at a given terminal size (docs/tasks/refactor-tui-dock-layout.md). Pure.
+ *
+ *   sidebar  ≥ 110 cols and ≥ 20 rows   right column; the top bar is not shown
+ *   topbar   80–109 cols, or a wide but short terminal (≥ 18 rows)   one row on top
+ *   bare     everything else            the input box's bottom edge only;
+ *                                       session and branch go to the terminal title
+ *
+ * The input box's bottom edge carries model and thinking in every tier, and
+ * the context share wherever there is no sidebar to hold it. Every status
+ * field has exactly one place per tier, so nothing is shown twice.
+ *
+ * The 110-column threshold is the author's choice (2026-10-06), set so the
+ * main column keeps the 75 columns OpenCode keeps beside its 42-column sidebar
+ * at its 121-column threshold (packages/tui routes/session/index.tsx).
+ */
+import { assertNever } from "../exhaustive.ts";
+
+export type Tier = "sidebar" | "topbar" | "bare";
+
+export interface ScreenLayout {
+  readonly tier: Tier;
+  /** Columns of the sidebar including its separator; 0 when hidden. */
+  readonly sidebarWidth: number;
+  readonly mainWidth: number;
+  readonly topbar: boolean;
+}
+
+export const SIDEBAR_MIN_COLUMNS = 110;
+export const SIDEBAR_MIN_ROWS = 20;
+export const TOPBAR_MIN_COLUMNS = 80;
+export const TOPBAR_MIN_ROWS = 18;
+/** The main column never gets narrower than this beside the sidebar. */
+export const MAIN_MIN_COLUMNS = 75;
+
+/** Sidebar content width (without the separator column). Wider terminals give it more room; assumed steps. */
+export function sidebarContentWidth(cols: number): number {
+  return cols >= 150 ? 42 : cols >= 130 ? 38 : 34;
+}
+
+export function screenLayout(cols: number, rows: number, sidebarWanted = true): ScreenLayout {
+  const c = Math.max(0, Math.floor(cols)), r = Math.max(0, Math.floor(rows));
+  if (sidebarWanted && c >= SIDEBAR_MIN_COLUMNS && r >= SIDEBAR_MIN_ROWS) {
+    const sidebarWidth = sidebarContentWidth(c) + 1;
+    return { tier: "sidebar", sidebarWidth, mainWidth: c - sidebarWidth, topbar: false };
+  }
+  if (c >= TOPBAR_MIN_COLUMNS && r >= TOPBAR_MIN_ROWS) return { tier: "topbar", sidebarWidth: 0, mainWidth: c, topbar: true };
+  return { tier: "bare", sidebarWidth: 0, mainWidth: c, topbar: false };
+}
+
+export const STATUS_FIELDS = ["model", "thinking", "context", "title", "workspace", "branch", "usage", "cost", "handoff", "tasks", "files", "background", "resources", "extension"] as const;
+export type StatusField = (typeof STATUS_FIELDS)[number];
+/** Screen surfaces only; the terminal title is outside the frame and listed separately. */
+export type Place = "sidebar" | "topbar" | "bottomEdge" | "hidden";
+
+/**
+ * The one place each field takes in a tier. Hidden fields stay one command
+ * away (/usage, /state, /tasks, /session); the terminal title also carries
+ * session and branch in every tier, outside the frame.
+ */
+export function placement(tier: Tier): Readonly<Record<StatusField, Place>> {
+  switch (tier) {
+    case "sidebar":
+      return { model: "bottomEdge", thinking: "bottomEdge", context: "sidebar", title: "sidebar", workspace: "sidebar", branch: "sidebar",
+        usage: "sidebar", cost: "sidebar", handoff: "sidebar", tasks: "sidebar", files: "sidebar", background: "sidebar", resources: "sidebar", extension: "sidebar" };
+    case "topbar":
+      return { model: "bottomEdge", thinking: "bottomEdge", context: "bottomEdge", title: "topbar", workspace: "topbar", branch: "topbar",
+        usage: "hidden", cost: "topbar", handoff: "topbar", tasks: "hidden", files: "hidden", background: "topbar", resources: "hidden", extension: "topbar" };
+    case "bare":
+      return { model: "bottomEdge", thinking: "bottomEdge", context: "bottomEdge", title: "hidden", workspace: "hidden", branch: "hidden",
+        usage: "hidden", cost: "hidden", handoff: "hidden", tasks: "hidden", files: "hidden", background: "hidden", resources: "hidden", extension: "hidden" };
+    default: return assertNever(tier, "placement");
+  }
+}