@visual-z/xeno 0.1.0

package/src/tui/select.ts

@@ -0,0 +1,240 @@
+/**
+ * A pickable list: applySelectKey(state, key) is pure, renderSelect paints.
+ *
+ * The visible window follows the selection so a /model list of dozens
+ * does not dump every row into the live region. An empty list must say
+ * why it is empty -- a blank box looks like a render bug.
+ */
+
+import { assertNever } from "./exhaustive.ts";
+import type { Key } from "./keys.ts";
+import type { Component } from "./text.ts";
+import { displayWidth } from "./width.ts";
+import { PLAIN_ATTRS, paint, type Style } from "./style.ts";
+import { Input } from "../vendor/pi-tui/components/input.ts";
+import { SelectList as PiSelectList } from "../vendor/pi-tui/components/select-list.ts";
+import { fuzzyFilter as piFuzzyFilter } from "../vendor/pi-tui/fuzzy.ts";
+import { truncateToWidth } from "../vendor/pi-tui/utils.ts";
+import { encodeKey, keyMatches } from "./input.ts";
+
+/**
+ * Default visible rows. Assumed, not measured: enough to scan a /model
+ * list without eating the whole scrollback. Callers pass maxVisible.
+ */
+export const DEFAULT_MAX_VISIBLE = 10;
+
+export interface SelectItem {
+  readonly value: string;
+  readonly label: string;
+  readonly description?: string;
+}
+
+export interface CreateSelectOptions {
+  readonly maxVisible?: number;
+  readonly emptyMessage?: string;
+  readonly style?: Style;
+  readonly title?: string;
+  readonly selectedValue?: string;
+  readonly search?: boolean;
+  readonly hint?: string;
+}
+
+export interface SelectState {
+  readonly items: readonly SelectItem[];
+  readonly selected: number;
+  readonly maxVisible: number;
+  readonly confirmed: SelectItem | null;
+  readonly cancelled: boolean;
+  readonly emptyMessage: string;
+}
+
+export function createSelect(
+  items: readonly SelectItem[],
+  opts: CreateSelectOptions = {},
+): SelectState {
+  return {
+    items,
+    selected: 0,
+    maxVisible: opts.maxVisible ?? DEFAULT_MAX_VISIBLE,
+    confirmed: null,
+    cancelled: false,
+    emptyMessage: opts.emptyMessage ?? "No matching items",
+  };
+}
+
+export function applySelectKey(state: SelectState, key: Key): SelectState {
+  switch (key.type) {
+    case "up":
+      return move(state, -1);
+    case "down":
+      return move(state, 1);
+    case "enter":
+      return confirm(state);
+    case "escape":
+      return { ...state, cancelled: true, confirmed: null };
+    case "char":
+    case "backspace":
+    case "delete":
+    case "tab":
+    case "left":
+    case "right":
+    case "home":
+    case "end":
+    case "pageup":
+    case "pagedown":
+    case "ctrl":
+    case "alt":
+      return state;
+    default:
+      return assertNever(key, "applySelectKey");
+  }
+}
+
+function move(state: SelectState, dir: -1 | 1): SelectState {
+  const n = state.items.length;
+  if (n === 0) return state;
+  const selected = (state.selected + dir + n) % n;
+  return { ...state, selected, confirmed: null, cancelled: false };
+}
+
+function confirm(state: SelectState): SelectState {
+  const item = state.items[state.selected];
+  if (item === undefined) return state;
+  return { ...state, confirmed: item, cancelled: false };
+}
+
+interface Window {
+  readonly start: number;
+  readonly end: number;
+}
+
+function visibleWindow(state: SelectState): Window {
+  const n = state.items.length;
+  const cap = state.maxVisible;
+  if (n <= cap) return { start: 0, end: n };
+  const start = Math.max(
+    0,
+    Math.min(state.selected - Math.floor(cap / 2), n - cap),
+  );
+  return { start, end: Math.min(start + cap, n) };
+}
+
+/**
+ * Truncate on display columns. Slicing with s.length would cut a CJK
+ * label in half and the next cell would paint garbage.
+ */
+function truncate(s: string, width: number): string {
+  if (width <= 0) return "";
+  if (displayWidth(s) <= width) return s;
+  let out = "";
+  let w = 0;
+  for (const ch of s) {
+    const cw = displayWidth(ch);
+    if (w + cw > width) break;
+    out += ch;
+    w += cw;
+  }
+  return out;
+}
+
+export function renderSelect(state: SelectState, width: number, style?: Style): string[] {
+  if (state.items.length === 0) return [state.emptyMessage];
+
+  const { start, end } = visibleWindow(state);
+  const lines: string[] = [];
+  for (let i = start; i < end; i++) {
+    const item = state.items[i];
+    if (item === undefined) continue;
+    const selected = i === state.selected;
+    const prefix = selected ? "→ " : "  ";
+    const budget = width - displayWidth(prefix);
+    let body = item.label;
+    const desc = item.description;
+    if (desc !== undefined && desc.length > 0) body = `${item.label}  ${desc}`;
+    const line = prefix + truncate(body, budget);
+    lines.push(
+      selected && style !== undefined ? paint(line, { ...PLAIN_ATTRS, selected: true }, style) : line,
+    );
+  }
+
+  const hidden = state.items.length - (end - start);
+  // Card copy is Chinese on purpose: this is the one user-visible string
+  // the completion definition named. English would silently relax it.
+  if (hidden > 0) lines.push(`还有 ${hidden} 条`);
+  return lines;
+}
+
+export class SelectList implements Component {
+  private current: SelectState;
+  private style: Style | undefined;
+  private readonly items: readonly SelectItem[];
+  private readonly options: CreateSelectOptions;
+  private readonly search = new Input({ prompt: "Search: " });
+  private list: PiSelectList;
+  onInput: ((data: string) => void) | undefined;
+
+  constructor(items: readonly SelectItem[], opts: CreateSelectOptions = {}) {
+    this.current = createSelect(items, opts);
+    this.items = items;
+    this.options = opts;
+    this.style = opts.style;
+    this.list = this.makeList();
+    this.list.setSelectedIndex(Math.max(0, items.findIndex((item) => item.value === opts.selectedValue)));
+  }
+
+  get state(): SelectState {
+    const selected = this.list.getSelectedItem();
+    return { ...this.current, selected: Math.max(0, this.current.items.findIndex((item) => item.value === selected?.value)) };
+  }
+
+  applyKey(key: Key): SelectState {
+    return this.acceptInput(encodeKey(key));
+  }
+
+  get focused(): boolean { return this.search.focused; }
+  set focused(value: boolean) { this.search.focused = value; }
+  invalidate(): void { this.search.invalidate(); this.list.invalidate(); }
+  handleInput(data: string): void { if (this.onInput) this.onInput(data); else this.acceptInput(data); }
+
+  setStyle(style: Style): void {
+    if (this.style === style) return;
+    const selected = this.state.selected;
+    this.style = style;
+    this.list = this.makeList();
+    this.list.setSelectedIndex(selected);
+  }
+
+  acceptInput(data: string): SelectState {
+    this.current = { ...this.current, confirmed: null, cancelled: false };
+    if (["up", "down", "enter", "escape", "ctrl+c"].some((key) => keyMatches(data, key))) this.list.handleInput(data);
+    else if (keyMatches(data, "pageUp") || keyMatches(data, "pageDown")) {
+      this.list.setSelectedIndex(this.state.selected + (keyMatches(data, "pageUp") ? -1 : 1) * this.current.maxVisible);
+    } else if (this.options.search !== false) {
+      this.search.handleInput(data);
+      const filtered = piFuzzyFilter([...this.items], this.search.getValue(), (item) => `${item.label} ${item.description ?? ""}`);
+      this.current = { ...this.current, items: filtered, selected: 0 };
+      this.list = this.makeList();
+    }
+    return this.state;
+  }
+
+  private makeList(): PiSelectList {
+    const selected = (text: string) => this.style ? paint(text, { ...PLAIN_ATTRS, selected: true }, this.style) : text;
+    const dim = (text: string) => this.style ? paint(text, { ...PLAIN_ATTRS, dim: true }, this.style) : text;
+    const list = new PiSelectList([...this.current.items], this.current.maxVisible, {
+      selectedPrefix: selected, selectedText: selected, description: dim, scrollInfo: dim, noMatch: dim,
+    });
+    list.onSelect = (item) => { this.current = { ...this.current, confirmed: item }; };
+    list.onCancel = () => { this.current = { ...this.current, cancelled: true }; };
+    return list;
+  }
+
+  render(width: number): string[] {
+    if (width <= 0) return [""];
+    const lines = [this.options.title ?? "Select"];
+    if (this.options.search !== false) lines.push(...this.search.render(width));
+    lines.push(...(this.current.items.length ? this.list.render(Math.max(4, width)) : [this.current.emptyMessage]));
+    lines.push(this.options.hint ?? "↑↓ select · Enter confirm · Esc cancel");
+    return lines.map((line) => truncateToWidth(line, width, ""));
+  }
+}

package/src/tui/settings.ts

@@ -0,0 +1,40 @@
+import { SettingsList, type SettingItem } from "../vendor/pi-tui/components/settings-list.ts";
+import { truncateToWidth } from "../vendor/pi-tui/utils.ts";
+import { PLAIN_ATTRS, paint, type Style } from "./style.ts";
+
+/** Pi owns settings navigation and cycling; apps persists the returned changes. */
+export class Settings {
+  private readonly items: SettingItem[];
+  private list: SettingsList;
+  private style: Style;
+  private changes: { id: string; value: string }[] = [];
+  cancelled = false;
+  onInput: ((data: string) => void) | undefined;
+  constructor(items: SettingItem[], style: Style) {
+    this.items = items;
+    this.style = style;
+    this.list = this.createList();
+  }
+  private createList(): SettingsList {
+    return new SettingsList(this.items, 8, {
+      label: (text, selected) => paint(text, { ...PLAIN_ATTRS, selected }, this.style),
+      value: (text) => paint(text, { ...PLAIN_ATTRS, status: true }, this.style),
+      description: (text) => paint(text, { ...PLAIN_ATTRS, dim: true }, this.style),
+      cursor: "→ ", hint: (text) => paint(text, { ...PLAIN_ATTRS, dim: true }, this.style),
+    }, (id, value) => { this.changes.push({ id, value }); }, () => { this.cancelled = true; }, { enableSearch: true });
+  }
+  setStyle(style: Style): void { this.style = style; }
+  handleInput(data: string): void { if (this.onInput) this.onInput(data); else this.acceptInput(data); }
+  acceptInput(data: string): { id: string; value: string }[] {
+    this.changes = [];
+    this.list.handleInput(data);
+    return this.changes;
+  }
+  updateValue(id: string, value: string): void { this.list.updateValue(id, value); }
+  invalidate(): void { this.list.invalidate(); }
+  render(width: number): string[] {
+    if (width <= 0) return [""];
+    return ["Settings · changes apply immediately", ...this.list.render(Math.max(8, width))]
+      .map((line) => truncateToWidth(line, width, ""));
+  }
+}

package/src/tui/statusline.ts

@@ -0,0 +1,162 @@
+/**
+ * Footer: pi's two-line shape, xeno's cut budget.
+ *
+ * Line 1 is cwd (with git branch) and session name. Line 2 is usage
+ * (↑ ↓ R W CH), cost, the context gauge, and the model. The gauge's
+ * denominator is shouldCut's triggerTokens, not a model context window —
+ * that number is the reason this project has a TUI at all.
+ *
+ * State in, string[] out. No terminal, no clock, no git.
+ */
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import type { Component } from "./text.ts";
+import { displayWidth } from "./width.ts";
+import { PLAIN_ATTRS, paint, type Style } from "./style.ts";
+
+export interface StatusState {
+  cwd: string;
+  branch: string | null;
+  tokens: number;
+  triggerTokens: number;
+  model: string;
+  thinking: string;
+  /**
+   * From shouldCut in apps, not inferred from the percentage. TUI must not
+   * recompute minNodeWorkTokens -- that floor lives in core.
+   */
+  cut: boolean;
+  reason: string;
+  sessionName?: string;
+  home?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  cacheHitRate?: number;
+  cost?: number;
+  /** Follow-ups waiting; painted in the stats line so it is not truncated off a padded row. */
+  queued?: number;
+}
+
+/** Kept so /hotkeys and the queue count can still name the bindings. */
+export const STATUS_HINT = "escape interrupt · / commands · /quit · ctrl+o tools · ctrl+t think";
+
+const ELLIPSIS = "...";
+
+/**
+ * Compact token counts the way pi's footer does. 30_000 → "30k" so the
+ * spelling matches the number shouldCut compares.
+ */
+export function formatTokens(count: number): string {
+  if (count < 1000) return count.toString();
+  if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+  if (count < 1000000) return `${Math.round(count / 1000)}k`;
+  if (count < 10000000) return `${(count / 1000000).toFixed(1)}M`;
+  return `${Math.round(count / 1000000)}M`;
+}
+
+export function formatCwdForFooter(cwd: string, home: string | undefined): string {
+  if (!home) return cwd;
+  const resolvedCwd = resolve(cwd);
+  const resolvedHome = resolve(home);
+  const relativeToHome = relative(resolvedHome, resolvedCwd);
+  const isInsideHome =
+    relativeToHome === "" ||
+    (relativeToHome !== ".." && !relativeToHome.startsWith(`..${sep}`) && !isAbsolute(relativeToHome));
+  if (!isInsideHome) return cwd;
+  return relativeToHome === "" ? "~" : `~${sep}${relativeToHome}`;
+}
+
+export function renderStatus(state: StatusState, width: number, style?: Style): string[] {
+  const w = Math.max(0, width);
+  const pwd = pwdLine(state, w);
+  const stats = statsLine(state, w);
+  const lines = [pwd, stats];
+  if (style === undefined) return lines;
+  const attrs = { ...PLAIN_ATTRS, status: true, dim: true };
+  return lines.map((line) => paint(line, attrs, style));
+}
+
+export function withStatus(body: Component, state: StatusState): Component {
+  return {
+    render(width: number): string[] {
+      return [...body.render(width), ...renderStatus(state, width)];
+    },
+  };
+}
+
+function pwdLine(state: StatusState, width: number): string {
+  let pwd = formatCwdForFooter(state.cwd, state.home);
+  if (state.branch) pwd = `${pwd} (${state.branch})`;
+  if (state.sessionName) pwd = `${pwd} • ${state.sessionName}`;
+  return truncateToWidth(pwd, width);
+}
+
+function statsLine(state: StatusState, width: number): string {
+  const parts: string[] = [];
+  if (state.inputTokens) parts.push(`↑${formatTokens(state.inputTokens)}`);
+  if (state.outputTokens) parts.push(`↓${formatTokens(state.outputTokens)}`);
+  if (state.cacheRead) parts.push(`R${formatTokens(state.cacheRead)}`);
+  if (state.cacheWrite) parts.push(`W${formatTokens(state.cacheWrite)}`);
+  if (
+    ((state.cacheRead ?? 0) > 0 || (state.cacheWrite ?? 0) > 0) &&
+    state.cacheHitRate !== undefined
+  ) {
+    parts.push(`CH${state.cacheHitRate.toFixed(1)}%`);
+  }
+  if (state.cost !== undefined && state.cost > 0) {
+    parts.push(`$${state.cost.toFixed(3)}`);
+  }
+  if (state.queued !== undefined && state.queued > 0) {
+    parts.push(`${state.queued} queued`);
+  }
+
+  // Floor, not round: 29999/30000 must not read as 100% while shouldCut
+  // is still below_trigger. Pi's shape is N%/Mk — the Mk is our trigger.
+  const trigger = state.triggerTokens;
+  const pct = trigger <= 0 ? 0 : Math.floor((100 * state.tokens) / trigger);
+  parts.push(`${pct}%/${formatTokens(trigger)}`);
+
+  let statsLeft = parts.join(" ");
+  if (displayWidth(statsLeft) > width) {
+    statsLeft = truncateToWidth(statsLeft, width);
+  }
+
+  let right = state.model;
+  if (state.thinking.length > 0) {
+    right = `${state.model} • ${state.thinking}`;
+  }
+  const leftW = displayWidth(statsLeft);
+  const rightW = displayWidth(right);
+  const minPadding = 2;
+  if (leftW + minPadding + rightW <= width) {
+    return statsLeft + " ".repeat(width - leftW - rightW) + right;
+  }
+  const availableForRight = width - leftW - minPadding;
+  if (availableForRight > 0) {
+    const truncatedRight = truncateToWidth(right, availableForRight);
+    const pad = Math.max(0, width - leftW - displayWidth(truncatedRight));
+    return statsLeft + " ".repeat(pad) + truncatedRight;
+  }
+  return statsLeft;
+}
+
+function truncateToWidth(s: string, width: number): string {
+  if (width <= 0) return "";
+  if (displayWidth(s) <= width) return s;
+  const ew = displayWidth(ELLIPSIS);
+  if (width <= ew) return takePrefix(s, width);
+  return takePrefix(s, width - ew) + ELLIPSIS;
+}
+
+function takePrefix(s: string, width: number): string {
+  let out = "";
+  let w = 0;
+  for (const ch of s) {
+    const cw = displayWidth(ch);
+    if (w + cw > width) break;
+    out += ch;
+    w += cw;
+  }
+  return out;
+}

package/src/tui/style.ts

@@ -0,0 +1,205 @@
+/**
+ * SGR composition for markdown.
+ *
+ * Terminals do not keep attributes across a newline, and the differential
+ * renderer rewrites by line (`src/tui/render.ts`). A wrap-the-whole-string
+ * helper would leave only the first row with an open code, so a later
+ * rewrite of row 2 paints in the default style. Every output row therefore
+ * carries its own open and close.
+ *
+ * Identity emits no ESC bytes: `-p` and pipes parse the transcript, and a
+ * CSI in that stream is a parse error waiting for a script (D17, same
+ * reason `createPalette(false)` exists).
+ *
+ * Colours are data: createStyle reads token → SGR params. Hard-coding a
+ * CSI colour here would be a colour the theme cannot reach.
+ */
+
+export interface Attrs {
+  readonly bold: boolean;
+  readonly italic: boolean;
+  readonly dim: boolean;
+  readonly code: boolean;
+  readonly heading: boolean;
+  readonly link: boolean;
+  /** Optional: tool diffs and exit codes. Absent keeps markdown Attrs unchanged. */
+  readonly red?: boolean;
+  readonly green?: boolean;
+  readonly yellow?: boolean;
+  readonly thinking?: boolean;
+  readonly tool?: boolean;
+  readonly result?: boolean;
+  readonly error?: boolean;
+  readonly status?: boolean;
+  readonly prompt?: boolean;
+  readonly selected?: boolean;
+}
+
+export const PLAIN_ATTRS: Attrs = {
+  bold: false,
+  italic: false,
+  dim: false,
+  code: false,
+  heading: false,
+  link: false,
+};
+
+export interface Style {
+  open(attrs: Attrs): string;
+  close(attrs: Attrs): string;
+  token?(name: string, text: string): string;
+}
+
+/**
+ * Token → SGR colour params. Same names as core/theme.ts; duplicated so
+ * tui never imports core. Empty string is the terminal default.
+ */
+export type ColorTokens = {
+  readonly text: string;
+  readonly thinkingText: string;
+  readonly toolTitle: string;
+  readonly toolOutput: string;
+  readonly error: string;
+  readonly toolDiffAdded: string;
+  readonly toolDiffRemoved: string;
+  readonly status: string;
+  readonly prompt: string;
+  readonly selectedBg: string;
+  readonly muted: string;
+  readonly warning: string;
+  readonly mdHeading: string;
+  readonly mdCode: string;
+  readonly mdLink: string;
+};
+
+/** Must stay in lockstep with core/theme.ts dark builtin. */
+export const DEFAULT_COLORS: ColorTokens = {
+  "text": "38;2;212;212;212",
+  "thinkingText": "38;2;128;128;128",
+  "toolTitle": "38;2;212;212;212",
+  "toolOutput": "38;2;128;128;128",
+  "error": "38;2;204;102;102",
+  "toolDiffAdded": "38;2;181;189;104",
+  "toolDiffRemoved": "38;2;204;102;102",
+  "status": "38;2;128;128;128",
+  "prompt": "38;2;212;212;212",
+  "selectedBg": "48;2;58;58;74",
+  "muted": "38;2;128;128;128",
+  "warning": "38;2;255;255;0",
+  "mdHeading": "38;2;240;198;116",
+  "mdCode": "38;2;138;190;183",
+  "mdLink": "38;2;129;162;190"
+};
+
+function anyAttr(a: Attrs, color: string): boolean {
+  return (
+    a.bold ||
+    a.italic ||
+    a.dim ||
+    a.code ||
+    a.heading ||
+    a.link ||
+    a.red === true ||
+    a.green === true ||
+    a.yellow === true ||
+    a.thinking === true ||
+    a.tool === true ||
+    a.result === true ||
+    a.error === true ||
+    a.status === true ||
+    a.prompt === true ||
+    a.selected === true ||
+    color.length > 0
+  );
+}
+
+function pickColor(attrs: Attrs, colors: ColorTokens): string {
+  if (attrs.selected === true) return colors.selectedBg;
+  if (attrs.prompt === true) return colors.prompt;
+  if (attrs.status === true) return colors.status;
+  if (attrs.thinking === true) return colors.thinkingText;
+  if (attrs.error === true) return colors.error;
+  if (attrs.red === true) return colors.toolDiffRemoved;
+  if (attrs.green === true) return colors.toolDiffAdded;
+  if (attrs.yellow === true) return colors.warning;
+  if (attrs.tool === true) return colors.toolTitle;
+  if (attrs.result === true) return colors.toolOutput;
+  if (attrs.code) return colors.mdCode;
+  if (attrs.heading) return colors.mdHeading;
+  if (attrs.link) return colors.mdLink;
+  if (attrs.dim) return colors.muted;
+  return colors.text;
+}
+
+/** Full reset, not a stacked 22/23/24. Nested closes would drop a wrapping attr on wrap. */
+const RESET = "\x1b[0m";
+
+export const IDENTITY: Style = {
+  open: () => "",
+  close: () => "",
+};
+
+/**
+ * Build a Style from theme tokens. `enabled` is the NO_COLOR / non-tty gate:
+ * a themed Style that still emits ESC in a pipe is the same class of bug as
+ * createPalette(true) on stdout that is not a tty.
+ */
+export function createStyle(colors: { readonly [token: string]: string }, enabled = true): Style {
+  if (!enabled) return IDENTITY;
+  const tokens: ColorTokens = {
+    text: colors["text"] ?? "",
+    thinkingText: colors["thinkingText"] ?? "",
+    toolTitle: colors["toolTitle"] ?? "",
+    toolOutput: colors["toolOutput"] ?? "",
+    error: colors["error"] ?? "",
+    toolDiffAdded: colors["toolDiffAdded"] ?? "",
+    toolDiffRemoved: colors["toolDiffRemoved"] ?? "",
+    status: colors["status"] ?? "",
+    prompt: colors["prompt"] ?? "",
+    selectedBg: colors["selectedBg"] ?? "",
+    muted: colors["muted"] ?? "",
+    warning: colors["warning"] ?? "",
+    mdHeading: colors["mdHeading"] ?? "",
+    mdCode: colors["mdCode"] ?? "",
+    mdLink: colors["mdLink"] ?? "",
+  };
+  return {
+    token(name, text) {
+      const color = colors[name];
+      return color ? `\x1b[${color}m${text}${RESET}` : text;
+    },
+    open(attrs) {
+      const color = pickColor(attrs, tokens);
+      if (!anyAttr(attrs, color)) return "";
+      const params: string[] = [];
+      if (attrs.bold || attrs.heading) params.push("1");
+      if (attrs.italic) params.push("3");
+      if (attrs.link) params.push("4");
+      if (color.length > 0) params.push(...color.split(";"));
+      const dim = attrs.dim ? "\x1b[2m" : "";
+      return dim + (params.length > 0 ? `\x1b[${params.join(";")}m` : "");
+    },
+    close(attrs) {
+      const color = pickColor(attrs, tokens);
+      return anyAttr(attrs, color) ? RESET : "";
+    },
+  };
+}
+
+export const ANSI: Style = createStyle(DEFAULT_COLORS);
+
+export function withDim(base: Style): Style {
+  return {
+    open(attrs) {
+      return base.open({ ...attrs, dim: true });
+    },
+    close(attrs) {
+      return base.close({ ...attrs, dim: true });
+    },
+  };
+}
+
+export function paint(text: string, attrs: Attrs, style: Style): string {
+  if (text.length === 0) return text;
+  return style.open(attrs) + text + style.close(attrs);
+}

package/src/tui/terminal.ts

@@ -0,0 +1,30 @@
+/**
+ * The only thing a renderer can be observed to do is write bytes.
+ *
+ * A real tty makes that unassertable -- tests would have to inspect a live
+ * terminal's screen, and would change its state while doing so. Injecting
+ * this interface is what makes "a frame that changed nothing writes nothing"
+ * a unit test rather than a hope.
+ */
+
+export interface Terminal {
+  readonly columns: number;
+  readonly rows: number;
+  write(data: string): void;
+}
+
+/**
+ * A pty opened without TIOCSWINSZ reports `columns === 0`, not
+ * `undefined`. `n ?? 80` keeps the zero, SelectList's truncate budget
+ * goes negative, and every label becomes "" -- `/model` shows only `→`.
+ * Treat non-positive as "size unknown" and fall back to the same 80
+ * StdoutTerminal already used for a missing ioctl.
+ */
+export function usableColumns(n: number | undefined): number {
+  return n && n > 0 ? n : 80;
+}
+
+/** Same trap as usableColumns: a 0-row ioctl is not a 0-row screen. */
+export function usableRows(n: number | undefined): number {
+  return n && n > 0 ? n : 24;
+}