@semalt-ai/code 1.8.1 → 1.8.4

package/lib/ui/status-bar.js

@@ -1,15 +1,32 @@
 'use strict';
 
-const { RST, DIM, FG_RED, SPINNER_DEFS } = require('./ansi');
-const { stripAnsi } = require('./utils');
+const { RST, DIM, FG_RED, FG_DARK, SPINNER_DEFS } = require('./ansi');
+const { UI_THEME } = require('./theme');
+const { stripAnsi, termWidth } = require('./utils');
 
+// Status bar is a *content producer* only. It builds a single line string
+// and hands it to the UI orchestrator via the onChange callback; the
+// orchestrator composes the full live region (status + input + hints) and
+// pushes it through the shared writer in one serialized burst. No direct
+// stdout writes happen here, so the status-bar timer can't interleave
+// mid-bubble.
 class FullStatusBar {
-  constructor(layout) {
+  constructor(layout, onChange) {
     this._layout = layout;
+    this._onChange = typeof onChange === 'function' ? onChange : () => {};
     this._state = 'idle';
     this._label = 'Ready';
     this._model = '';
-    this._totalTokens = 0;
+    // Current-context indicator state. "Reported" is the last API-reported
+    // prompt_tokens (exact, authoritative). "Pending" is an approximate delta
+    // for messages added to the conversation after the last report — user
+    // input between turns, plus the assistant/tool-result text from the
+    // previous turn that will land in the next prompt. Rendered sum:
+    //   used = _reportedContext + _pendingDelta
+    // Reset to pending=0 when a fresh prompt_tokens arrives.
+    this._reportedContext = 0;
+    this._pendingDelta = 0;
+    this._contextLimit = null;
     this._speed = 0;
     this._streamStart = null;
     this._streamTokens = 0;
@@ -17,23 +34,24 @@ class FullStatusBar {
     this._animIdx = 0;
     this._animTimer = null;
     this._paused = false;
-    this._clockTimer = setInterval(() => this._renderBar(), 1000);
+    // Clock tick drives the `HH:MM:SS` part of the right-hand side. Every
+    // tick just notifies the orchestrator to re-push the live region — the
+    // compound erase+redraw goes through the writer's queue so a tick
+    // falling mid-bubble can't produce a torn frame.
+    this._clockTimer = setInterval(() => this._notify(), 1000);
   }
 
   pause()  { this._paused = true; }
-  resume() { this._paused = false; this._renderBar(); }
+  resume() { this._paused = false; this._notify(); }
 
   setModel(name) {
     this._model = name || '';
-    this._renderBar();
+    this._notify();
   }
 
   update(state, label) {
     this._state = state || 'idle';
     if (label !== undefined) this._label = label;
-
-    // An explicit update must always be visible — unpause so _renderBar() runs.
-    // The pause flag only suppresses timer-driven clock/spinner redraws.
     this._paused = false;
 
     if (state === 'streaming') {
@@ -44,12 +62,11 @@ class FullStatusBar {
 
     const animStates = ['thinking', 'streaming', 'tool', 'waiting_download'];
     if (animStates.includes(state) && !this._animTimer) {
-      this._animTimer = setInterval(() => { this._animIdx++; this._renderBar(); }, 100);
+      this._animTimer = setInterval(() => { this._animIdx++; this._notify(); }, 100);
     } else if (!animStates.includes(state) && this._animTimer) {
       clearInterval(this._animTimer); this._animTimer = null; this._animIdx = 0;
     }
-    if (state === 'idle') this.drawSeparator();
-    this._renderBar();
+    this._notify();
   }
 
   onToken() {
@@ -61,28 +78,63 @@ class FullStatusBar {
         const elapsed = (Date.now() - this._streamStart) / 1000;
         this._speed = elapsed > 0 ? Math.round(this._streamTokens / elapsed) : 0;
       }
-      this._renderBar();
+      this._notify();
     }
   }
 
+  // Called by the agent loop after each API response (authoritative) and by
+  // resolveTokenLimit on session start (limit only). Setting contextTokens
+  // clears pending because the freshly reported prompt_tokens already
+  // accounts for every message that was on the wire.
   updateMetrics(data) {
-    if (data && data.totalTokens !== undefined) this._totalTokens = data.totalTokens;
-    this._renderBar();
+    if (!data) { this._notify(); return; }
+    if (typeof data.contextTokens === 'number') {
+      this._reportedContext = data.contextTokens;
+      this._pendingDelta = 0;
+    }
+    if (data.tokenLimit && typeof data.tokenLimit.limit === 'number') {
+      this._contextLimit = data.tokenLimit.limit;
+    }
+    this._notify();
   }
 
-  liveUpdate(fields) {
-    if (fields && fields.tokens) {
-      const n = parseInt(String(fields.tokens), 10);
-      if (!isNaN(n)) this._totalTokens = n;
+  setContextLimit(limit) {
+    this._contextLimit = (Number.isInteger(limit) && limit > 0) ? limit : null;
+    this._notify();
+  }
+
+  setReportedContext(promptTokens) {
+    if (typeof promptTokens === 'number' && promptTokens >= 0) {
+      this._reportedContext = promptTokens;
+      this._pendingDelta = 0;
+      this._notify();
     }
-    this._renderBar();
   }
 
-  _renderBar() {
-    if (this._paused) return;
+  addPendingTokens(n) {
+    if (typeof n === 'number' && n > 0) {
+      this._pendingDelta += n;
+      this._notify();
+    }
+  }
+
+  // Render the status bar as a single line string. Used by the UI composer
+  // to build the live region. ALWAYS returns a string — the status row is a
+  // permanent fixture of the live region, never omitted. Missing data
+  // renders as a short placeholder ("—") so the row width is stable.
+  // `_paused` is honored by suppressing the `_notify` *tick* (no forced
+  // redraws while idle) but the row itself is still present when the
+  // composer asks for it.
+  renderLine() {
     const layout = this._layout;
     const cols = layout.cols;
-    const row = layout.statusRow;
+    // Budget one less than cols so `_fitOneRow` in the writer never has to
+    // chop a visible char off the end — mid-word truncation ("190,507 tok"
+    // → "190,507 to") came from this row filling the full terminal width
+    // and getting cut at cols-1 downstream. Budgeting here also keeps the
+    // line safely inside a single physical row even if the terminal
+    // reflows on resize.
+    const maxCols = Math.max(1, cols - 1);
     let left = '';
     const state = this._state;
 
@@ -100,26 +152,111 @@ class FullStatusBar {
 
     const now = new Date();
     const timePart = `${String(now.getHours()).padStart(2,'0')}:${String(now.getMinutes()).padStart(2,'0')}:${String(now.getSeconds()).padStart(2,'0')}`;
-    const rightParts = [timePart];
-    if (this._model) rightParts.push(this._model);
-    const liveTokens = this._totalTokens + this._streamTokens;
-    rightParts.push(`${liveTokens.toLocaleString()} tok`);
-    if (state === 'streaming' && this._speed > 0) rightParts.push(`${this._speed} t/s`);
-
-    const rightVisible = rightParts.join(' · ');
-    const rightAnsi = `${DIM}${rightParts.join(` ${DIM}·${RST}${DIM} `)}${RST}`;
-    const leftLen = stripAnsi(left).length;
-    const rightLen = rightVisible.length;
-    const padding = Math.max(1, cols - leftLen - rightLen);
-    const line = left + ' '.repeat(padding) + rightAnsi;
-
-    process.stdout.write(`\x1b7\x1b[${row};1H\x1b[2K${line}\x1b8`);
+    // Field slots are paired: `visible` drives layout/padding; `ansi` is
+    // injected into the final rendered string. Keeping them side-by-side
+    // avoids double-counting ANSI escapes in the padding math and lets the
+    // token field override the surrounding DIM for its warning/error pct.
+    // `priority` is drop-priority: lower values are dropped first when the
+    // row doesn't fit the terminal width. Priority order (high→low):
+    //   model > tokens > time > speed
+    // so on narrow terminals the row silently loses speed, then time, then
+    // tokens, keeping the model name readable to the last. Never chop a
+    // field mid-character.
+    const tokenField = this._buildTokenField();
+    const fields = [
+      { visible: timePart,           ansi: timePart,           priority: 2 },
+      { visible: this._model || '—', ansi: this._model || '—', priority: 4 },
+      { visible: tokenField.visible, ansi: tokenField.ansi,    priority: 3 },
+    ];
+    if (state === 'streaming' && this._speed > 0) {
+      const s = `${this._speed} t/s`;
+      fields.push({ visible: s, ansi: s, priority: 1 });
+    }
+
+    const sep = ' · ';
+    const sepAnsi = ` ${RST}${DIM}·${RST}${DIM} `;
+    const leftWidth = termWidth(stripAnsi(left));
+    // Keep at least one space between left and right chrome when left is
+    // non-empty; when idle (left == '') the right can sit at column 0.
+    const gap = leftWidth > 0 ? 1 : 0;
+    const availableRight = Math.max(0, maxCols - leftWidth - gap);
+
+    const widthOf = (arr) => {
+      let w = 0;
+      for (let i = 0; i < arr.length; i++) {
+        if (i > 0) w += sep.length;
+        w += termWidth(arr[i].visible);
+      }
+      return w;
+    };
+
+    const keep = fields.slice();
+    while (keep.length > 0 && widthOf(keep) > availableRight) {
+      let minIdx = 0;
+      for (let i = 1; i < keep.length; i++) {
+        if (keep[i].priority < keep[minIdx].priority) minIdx = i;
+      }
+      keep.splice(minIdx, 1);
+    }
+
+    if (keep.length === 0) {
+      // Terminal too narrow for any right-hand field — render left only,
+      // padded to fill the budgeted row. Downstream truncation (if the
+      // left itself exceeds maxCols) is handled by `_fitOneRow`.
+      const padCount = Math.max(0, maxCols - leftWidth);
+      return left + ' '.repeat(padCount);
+    }
+
+    const rightWidth = widthOf(keep);
+    const rightAnsi = `${DIM}${keep.map((f) => f.ansi).join(sepAnsi)}${RST}`;
+    const padding = Math.max(gap > 0 ? gap : 0, maxCols - leftWidth - rightWidth);
+    return left + ' '.repeat(padding) + rightAnsi;
   }
 
-  drawSeparator() {
-    const layout = this._layout;
-    const { FG_DARK } = require('./ansi');
-    process.stdout.write(`\x1b7\x1b[${layout.separatorRow};1H\x1b[2K${FG_DARK}${'─'.repeat(layout.cols)}${RST}\x1b8`);
+  // Build the current-context indicator as a { visible, ansi } pair.
+  // `visible` is the plain text used for padding math; `ansi` carries the
+  // threshold color for the percentage (gray <70, amber 70-90, red ≥90).
+  // When the active profile reports no context_length, the "/ limit" and
+  // "(%)" portions are omitted.
+  _buildTokenField() {
+    const used = Math.max(0, (this._reportedContext | 0) + (this._pendingDelta | 0));
+    const usedStr = used.toLocaleString();
+    if (!this._contextLimit) {
+      const s = `${usedStr} tok`;
+      return { visible: s, ansi: s };
+    }
+    const limit = this._contextLimit;
+    const pct = limit > 0 ? Math.round((used / limit) * 100) : 0;
+    const limitStr = limit.toLocaleString();
+    const visible = `${usedStr} / ${limitStr} tok (${pct}%)`;
+    let pctAnsi = `${pct}%`;
+    if (pct >= 90) {
+      pctAnsi = `${RST}${UI_THEME.error}${pct}%${RST}${DIM}`;
+    } else if (pct >= 70) {
+      pctAnsi = `${RST}${UI_THEME.warning}${pct}%${RST}${DIM}`;
+    }
+    const ansi = `${usedStr} / ${limitStr} tok (${pctAnsi})`;
+    return { visible, ansi };
+  }
+
+  // Thin horizontal rule rendered above the status line. Kept as its own
+  // line in the live region so the composer can turn it on/off without
+  // affecting surrounding rows.
+  renderSeparator() {
+    const cols = this._layout.cols;
+    return `${FG_DARK}${'─'.repeat(Math.max(0, cols - 1))}${RST}`;
+  }
+
+  // Back-compat: older call sites (command.js, create-ui.js) call
+  // drawSeparator/_renderBar after every state change. These now just
+  // trigger a live-region refresh — the orchestrator composes the full
+  // region and serializes the write.
+  drawSeparator() { this._notify(); }
+  _renderBar()    { this._notify(); }
+
+  _notify() {
+    if (this._paused) { this._onChange(); return; }
+    this._onChange();
   }
 
   destroy() {

package/lib/ui/stream.js

@@ -4,6 +4,7 @@ const readline = require('readline');
 
 const { RST, DIM, FG_DARK, FG_CODE_BG, FG_CODE_BORDER, FG_CODE_LANG, FG_TAG, FG_FILEPATH, KEYWORDS } = require('./ansi');
 const { renderMarkdown, _mdInline } = require('./diff');
+const writer = require('./writer');
 
 const THINK_OPEN = '<think>', THINK_CLOSE = '</think>';
 
@@ -15,21 +16,17 @@ class StreamRenderer {
     this._showThink = opts.showThink || false;
     this.inToolCall = null;
     this._firstLinePrefix = opts.firstLinePrefix || null;
-    this._firstLineDone = false; this._firstToken = false;
+    this._firstLineDone = false;
     this._streamedText = ''; this._hasToolCall = false; this._linesWritten = 0;
   }
 
   _write(str) {
     for (let i = 0; i < str.length; i++) if (str[i] === '\n') this._linesWritten++;
+    // audit: allowed — non-TUI StreamRenderer, no live region to protect.
     process.stdout.write(str);
   }
 
   feed(chunk) {
-    if (!this._firstToken && chunk) {
-      this._firstToken = true;
-      const { StatusBar } = require('./legacy');
-      if (StatusBar.current) StatusBar.current.update({ status: 'streaming' });
-    }
     this._streamedText += chunk;
     this.buffer += chunk;
     while (this.buffer.includes('\n')) {
@@ -45,14 +42,13 @@ class StreamRenderer {
     if (this.inThinkBlock) { if (this._showThink) this._write(`${FG_DARK}⟨/thinking⟩${RST}\n`); this.inThinkBlock = false; }
     if (this.inToolCall) { this._renderToolCall(this.inToolCall); this.inToolCall = null; }
     if (this.inCodeBlock) { this._write(`  ${FG_CODE_BORDER}╰${'─'.repeat(50)}${RST}\n`); this.inCodeBlock = false; }
-    const { StatusBar } = require('./legacy');
-    if (StatusBar.current) StatusBar.current.update({ status: 'idle' });
     if (process.stdout.isTTY && !this._hasToolCall && !this._showThink && this._streamedText.trim()) {
       let prose = this._streamedText;
       let ts = prose.indexOf(THINK_OPEN);
       while (ts !== -1) { const te = prose.indexOf(THINK_CLOSE, ts); if (te !== -1) { prose = prose.slice(0, ts) + prose.slice(te + THINK_CLOSE.length); ts = prose.indexOf(THINK_OPEN); } else { prose = prose.slice(0, ts); break; } }
       prose = prose.split(THINK_CLOSE).join('');
       if (prose.trim()) {
+        // audit: allowed — non-TUI StreamRenderer, no live region to protect.
         if (this._linesWritten > 0) { readline.moveCursor(process.stdout, 0, -this._linesWritten); readline.cursorTo(process.stdout, 0); process.stdout.write('\x1b[0J'); }
         renderMarkdown(prose);
       }
@@ -134,11 +130,11 @@ class StreamRenderer {
   _renderToolCall(call) {
     this._hasToolCall = true;
     const name = call.name, lines = call.contentLines || [], content = lines.join('\n').trim();
-    if (name === 'write_file') { process.stdout.write(`  ${FG_TAG}◆ write_file${RST} ${FG_FILEPATH}${call.filePath || ''}${RST} ${FG_DARK}(${lines.length} lines)${RST}\n`); return; }
-    if (name === 'read_file') { process.stdout.write(`  ${FG_TAG}◆ read_file${RST} ${FG_FILEPATH}${content}${RST}\n`); return; }
-    if (name === 'exec' || name === 'shell' || name === 'run_command' || name === 'run') { process.stdout.write(`  ${FG_TAG}◆ exec${RST} ${FG_DARK}${content}${RST}\n`); return; }
+    if (name === 'write_file') { writer.scrollback(`  ${FG_TAG}◆ write_file${RST} ${FG_FILEPATH}${call.filePath || ''}${RST} ${FG_DARK}(${lines.length} lines)${RST}`); return; }
+    if (name === 'read_file') { writer.scrollback(`  ${FG_TAG}◆ read_file${RST} ${FG_FILEPATH}${content}${RST}`); return; }
+    if (name === 'exec' || name === 'shell' || name === 'run_command' || name === 'run') { writer.scrollback(`  ${FG_TAG}◆ exec${RST} ${FG_DARK}${content}${RST}`); return; }
     const preview = content.length > 80 ? content.slice(0, 77) + '...' : content;
-    process.stdout.write(`  ${FG_TAG}◆ ${name}${RST} ${FG_DARK}${preview}${RST}\n`);
+    writer.scrollback(`  ${FG_TAG}◆ ${name}${RST} ${FG_DARK}${preview}${RST}`);
   }
 
   _colorizeCode(line) {

package/lib/ui/terminal.js

@@ -0,0 +1,60 @@
+'use strict';
+
+// Process-level signal/exit wiring for the TUI. The actual terminal cleanup
+// (erase live region, reset SGR, show cursor, pop modes) lives in
+// writer.teardown() so every exit path runs the exact same single-write
+// sequence. This module just makes sure that sequence runs no matter how
+// the process dies.
+
+const writer = require('./writer');
+
+let _registered = false;
+
+// Kept for backwards compatibility with callers that publish viewport
+// metrics. The live-region writer doesn't need them — teardown computes
+// what to erase from its own live-region height.
+function setCleanupInfo(_info) {}
+
+// Idempotent. Safe to call from synchronous contexts including the 'exit'
+// handler. Delegates to writer.teardown(), which is the single source of
+// truth for what a "clean" terminal state looks like.
+function teardownTerminal() {
+  try { writer.teardown(); } catch {}
+}
+
+// Install process-level handlers. Called once by the entrypoint. Idempotent
+// so library code can also call it defensively without doubling handlers.
+function registerTerminalCleanup() {
+  if (_registered) return;
+  _registered = true;
+
+  // Normal exit + process.exit(): fires synchronously, last thing Node does.
+  // Catches every path that doesn't already manually call teardown.
+  process.on('exit', () => { try { writer.teardown(); } catch {} });
+
+  // Signals that should terminate the app. Cleanup first, then exit with
+  // the conventional 128+signum code. In TUI raw mode, Ctrl+C is consumed
+  // at the byte level and SIGINT is not delivered, so this handler only
+  // trips in non-raw contexts (one-shot commands, readline prompts, etc.).
+  process.on('SIGINT',  () => { try { writer.teardown(); } catch {} process.exit(130); });
+  process.on('SIGTERM', () => { try { writer.teardown(); } catch {} process.exit(143); });
+  process.on('SIGHUP',  () => { try { writer.teardown(); } catch {} process.exit(129); });
+
+  // Last-chance net: if something throws outside a try/catch, still
+  // restore terminal state before the stack trace prints.
+  process.on('uncaughtException', (err) => {
+    try { writer.teardown(); } catch {}
+    // audit: allowed — crash handler stderr after writer teardown.
+    try { console.error(err && err.stack ? err.stack : err); } catch {}
+    process.exit(1);
+  });
+
+  process.on('unhandledRejection', (reason) => {
+    try { writer.teardown(); } catch {}
+    // audit: allowed — crash handler stderr after writer teardown.
+    try { console.error(reason && reason.stack ? reason.stack : reason); } catch {}
+    process.exit(1);
+  });
+}
+
+module.exports = { teardownTerminal, registerTerminalCleanup, setCleanupInfo };

package/lib/ui/theme.js

@@ -0,0 +1,99 @@
+'use strict';
+
+const { bg256, fg256, bgRGB, fgRGB } = require('./ansi');
+
+// Shared chrome palette. Used by tool-status lines, debug blocks, meta
+// messages, and any other non-content surface. Diff bodies have their own
+// background palette below. Keep palette choices out of renderers — if a
+// colour is added to a status line, it should come from here.
+const UI_THEME = {
+  success: fg256(114),  // bright mint
+  warning: fg256(179),  // amber
+  error:   fg256(174),  // salmon
+  info:    fg256(75),   // light blue
+  muted:   fg256(240),  // dim gray — frames, metadata
+  subtle:  fg256(244),  // slightly less dim — secondary text
+  accent:  fg256(141),  // soft purple — tool names, IDs
+  default: '\x1b[39m',  // terminal default fg
+  // Per-category accent variations for tool-line chrome. Chosen from the
+  // pastel/light bands (100–180 range) so concurrent pending lines read
+  // as a coordinated palette rather than a rainbow. Keys mirror the
+  // values produced by TOOL_CATEGORIES so a lookup is categories[cat].
+  categories: {
+    net:    fg256(110),  // dusty blue    — http, download, upload
+    file:   fg256(151),  // soft sage     — file ops
+    cmd:    fg256(180),  // warm tan      — shell / exec
+    user:   fg256(217),  // pale rose     — ask_user
+    memory: fg256(183),  // light lavender — memory
+    env:    fg256(186),  // pale gold     — env vars
+    system: fg256(109),  // steel blue    — system_info
+    debug:  fg256(244),  // muted gray    — debug blocks
+    tool:   fg256(141),  // accent purple — fallback
+  },
+};
+
+// Indicator glyphs for status lines. Separated from colour so the renderer
+// can swap either independently (e.g. an ASCII-only fallback later).
+const UI_ICONS = {
+  pending: '●',
+  success: '✓',
+  error:   '✗',
+  retry:   '⟳',
+  warn:    '⚠',
+  bullet:  '●',
+};
+
+// Diff rendering palette. Each change-type carries both a 256-color and a
+// truecolor background so the renderer can pick based on COLORTERM at start.
+// Only this file names colors — keep magic numbers out of diff.js.
+const DIFF_THEME = {
+  added: {
+    bg256:  bg256(22),            // deep forest green
+    bgTC:   bgRGB(14, 40, 23),
+    signFg: fg256(114),           // bright mint
+    sign:   '+',
+  },
+  removed: {
+    bg256:  bg256(52),            // deep burgundy
+    bgTC:   bgRGB(50, 18, 20),
+    signFg: fg256(174),           // bright salmon
+    sign:   '-',
+  },
+  context: {
+    bg256:  '',
+    bgTC:   '',
+    signFg: '',
+    sign:   ' ',
+  },
+  gutter:     { bg256: '', bgTC: '' },
+  lineNumber: fg256(240),         // dim gray
+  code:       '\x1b[39m',         // terminal default fg
+  header:     '\x1b[1;38;5;75m',  // bold light blue
+  frame:      fg256(238),         // very dim gray
+};
+
+// Maps an agent-loop tool tag onto the short category shown before the
+// operation in a tool line ("file", "net", "shell"). Renderers should
+// fall back to the tag itself if the tag isn't listed here.
+//
+// Keys include BOTH the XML tag names (read_file, write_file, shell) and
+// the internal action names emitted by the native-function mapper (read,
+// write, exec). Normalization happens at lookup time so neither side needs
+// to know about the other's naming.
+const TOOL_CATEGORIES = {
+  exec: 'shell', shell: 'shell', run: 'shell', run_command: 'shell', bash: 'shell',
+  read: 'file', write: 'file', append: 'file',
+  read_file: 'file', write_file: 'file', create_file: 'file',
+  append_file: 'file', delete_file: 'file', edit_file: 'file',
+  list_dir: 'file', search_files: 'file', search_in_file: 'file',
+  replace_in_file: 'file', move_file: 'file', copy_file: 'file',
+  file_stat: 'file', make_dir: 'file', remove_dir: 'file',
+  http_get: 'net', download: 'net', upload: 'net',
+  ask_user: 'user',
+  store_memory: 'memory', recall_memory: 'memory', list_memories: 'memory',
+  get_env: 'env', set_env: 'env',
+  system_info: 'system',
+  debug: 'debug',
+};
+
+module.exports = { DIFF_THEME, UI_THEME, UI_ICONS, TOOL_CATEGORIES };

package/lib/ui/utils.js

@@ -7,11 +7,112 @@ function stripAnsi(str) {
   return str.replace(/\x1b\[[^m]*m/g, '');
 }
 
-function hr(char, color) {
-  const { FG_DARK, RST } = require('./ansi');
-  const c = char || '─';
-  const col = color || FG_DARK;
-  process.stdout.write(`${col}${c.repeat(getCols())}${RST}\n`);
+// Display-column width of a single codepoint. Factored out so truncateVisible
+// can reuse the width logic without rebuilding a per-character substring.
+function _cpWidth(cp) {
+  if (cp === 0) return 0;
+  if ((cp >= 0x0300 && cp <= 0x036F) ||
+      (cp >= 0x200B && cp <= 0x200F) ||
+      cp === 0x2060 ||
+      (cp >= 0xFE00 && cp <= 0xFE0F) ||
+      (cp >= 0xE0100 && cp <= 0xE01EF)) {
+    return 0;
+  }
+  if ((cp >= 0x3040 && cp <= 0x33FF) ||
+      (cp >= 0x3400 && cp <= 0x4DBF) ||
+      (cp >= 0x4E00 && cp <= 0x9FFF) ||
+      (cp >= 0xF900 && cp <= 0xFAFF) ||
+      (cp >= 0x2600 && cp <= 0x27BF) ||
+      (cp >= 0x1F300 && cp <= 0x1FAFF)) {
+    return 2;
+  }
+  return 1;
+}
+
+// Display-column width of a string. Handles ASCII/Latin/Cyrillic (1 col),
+// CJK ideographs + hiragana/katakana (2 cols), emoji in SMP pictograph
+// blocks and the dingbat/misc-symbols range (2 cols), and zero-width joiners,
+// combining marks, variation selectors (0 cols). Out-of-scope scripts
+// (Hangul, Thai, RTL) fall through as 1 col.
+function termWidth(str) {
+  if (!str) return 0;
+  let w = 0;
+  for (const ch of str) w += _cpWidth(ch.codePointAt(0));
+  return w;
+}
+
+// ANSI-aware, display-width-aware truncation to `maxCols` visible columns.
+// Walks the string once; CSI escape sequences (`\x1b[…final`) are copied
+// through verbatim without consuming any visible width. Visible-width math
+// uses _cpWidth, so a 2-col CJK glyph or emoji counts as 2 and combining
+// marks count as 0. Always terminates with `\x1b[0m` so the terminal isn't
+// left in a colored state at the truncation point (safe when no escape
+// preceded the cut — a redundant reset is a no-op).
+function truncateVisible(str, maxCols) {
+  if (!str) return '';
+  const max = Math.max(0, maxCols | 0);
+  if (max === 0) return '\x1b[0m';
+  const s = String(str);
+  const len = s.length;
+  let out = '';
+  let cols = 0;
+  let i = 0;
+  while (i < len) {
+    const code = s.charCodeAt(i);
+    // CSI: ESC '[' … final-byte-in-0x40..0x7E.
+    if (code === 0x1B && i + 1 < len && s.charCodeAt(i + 1) === 0x5B) {
+      let j = i + 2;
+      while (j < len) {
+        const c = s.charCodeAt(j);
+        if (c >= 0x40 && c <= 0x7E) { j++; break; }
+        j++;
+      }
+      out += s.slice(i, j);
+      i = j;
+      continue;
+    }
+    // Bare ESC or non-CSI escape lead-in: copy through as 0 width so it
+    // doesn't eat a column it never claimed.
+    if (code === 0x1B) { out += s[i]; i++; continue; }
+    const cp = s.codePointAt(i);
+    const clen = cp > 0xFFFF ? 2 : 1;
+    const w = _cpWidth(cp);
+    if (cols + w > max) break;
+    out += s.slice(i, i + clen);
+    cols += w;
+    i += clen;
+  }
+  return out + '\x1b[0m';
+}
+
+// Repeat a single-column glyph so the visible row is exactly `width` columns.
+// Accepts an optional `used` arg (columns already occupied) to fill the
+// remainder — handy for header lines like " LABEL ══════…" that need to
+// reach the right edge regardless of terminal size.
+function repeatToWidth(char, width, used) {
+  const w = Math.max(0, (width || 0) - (used || 0));
+  return (char || '─').repeat(w);
+}
+
+// Number of *physical* terminal rows that `text` occupies at the given
+// width. Uses termWidth (display columns) so emoji / CJK / combining marks
+// are counted correctly, and ceils each logical line's wrap count. An
+// empty line still occupies 1 row. This is the number to use whenever the
+// redraw logic cursor-ups to erase or when the layout grows to hold new
+// content — counting `text.split('\n').length` undercounts wrapped lines
+// and lets the trailing physical row leak into scrollback on the next
+// redraw (TUI duplicate-frame bug).
+function displayRows(text, termCols) {
+  if (text === undefined || text === null) return 0;
+  const cols = Math.max(1, termCols | 0);
+  const raw = stripAnsi(String(text));
+  const lines = raw.split('\n');
+  let rows = 0;
+  for (const line of lines) {
+    const w = termWidth(line);
+    rows += w === 0 ? 1 : Math.ceil(w / cols);
+  }
+  return rows;
 }
 
 function boxLine(text, width) {
@@ -42,4 +143,32 @@ function isPrintableKey(str, key) {
   return !/[\x00-\x1f\x7f]/.test(str);
 }
 
-module.exports = { getCols, getRows, stripAnsi, hr, boxLine, insertCharAt, removeCharAt, isPrintableKey };
+// Rough token count for context-size indicator. Not a real tokenizer — zero-dep
+// project can't afford tiktoken/BPE. Single pass over charCodeAt, no regex.
+// Ratios chosen so an all-ASCII English doc averages ~4 chars/token (OpenAI-ish),
+// while CJK-heavy Chinese/Japanese text (where one ideograph ≈ one token for
+// most BPE vocabs) scales toward ~2 chars/token. Mixed code+comments land in
+// the middle band. Used by the status bar only; never drives hard limits.
+function approxTokens(text) {
+  if (!text) return 0;
+  const str = typeof text === 'string' ? text : String(text);
+  const total = str.length;
+  if (total === 0) return 0;
+  let cjk = 0;
+  for (let i = 0; i < total; i++) {
+    const cp = str.charCodeAt(i);
+    if ((cp >= 0x3040 && cp <= 0x33FF) ||
+        (cp >= 0x3400 && cp <= 0x4DBF) ||
+        (cp >= 0x4E00 && cp <= 0x9FFF) ||
+        (cp >= 0xAC00 && cp <= 0xD7AF) ||
+        (cp >= 0xF900 && cp <= 0xFAFF)) {
+      cjk++;
+    }
+  }
+  const ratio = cjk / total;
+  if (ratio > 0.30) return Math.ceil(total / 2);
+  if (ratio > 0.10) return Math.ceil(total / 3);
+  return Math.ceil(total / 4);
+}
+
+module.exports = { getCols, getRows, stripAnsi, termWidth, truncateVisible, displayRows, repeatToWidth, boxLine, insertCharAt, removeCharAt, isPrintableKey, approxTokens };