@orbit-intelligence/orbit-agent 0.3.12

package/dist/src/tui/components/markdown.js

@@ -0,0 +1,384 @@
+import hljs from 'highlight.js/lib/common';
+import { marked } from 'marked';
+import { wrapText, truncate, padRight, width as visWidth, strip as stripAnsiText } from '../text.js';
+export function renderMarkdown(src, ctx) {
+    // Gemini/OpenRouter escape markdown punctuation (`\*`, `\"`, `\`\`\``, `\|`).
+    // Leaving those escapes in place defeats block detection (lists, code fences,
+    // tables), so undo the common ones before lexing.
+    const tokens = marked.lexer(unescapeModelEscapes(src));
+    const rctx = {
+        theme: ctx.theme,
+        width: ctx.width,
+        indent: 0,
+        headingLevel: 0,
+    };
+    const lines = [];
+    renderTokens(tokens, rctx, lines);
+    return lines;
+}
+/**
+ * Undo backslash escapes that language models add to markdown punctuation.
+ * Examples: `\*` → `*`, `\"` → `"`, `\`\`\`` → ` ``` `, `\|` → `|`, `\_` → `_`.
+ * Lines inside fenced code blocks are left untouched so code samples (e.g.
+ * `\d`, `\n`) never get mutated; backslash-letter pairs outside fences also
+ * stay intact. Only a backslash directly before markdown punctuation is
+ * consumed.
+ */
+function unescapeModelEscapes(src) {
+    const escaped = /\\+([\\*_`\[\]()#+\-.!><~|"':])/g;
+    const fenceCheck = /^(\s*)(```|~~~)/;
+    let inFence = false;
+    const out = [];
+    for (const line of src.split('\n')) {
+        if (fenceCheck.test(line)) {
+            inFence = !inFence;
+            out.push(line);
+            continue;
+        }
+        out.push(inFence || !line.includes('\\') ? line : line.replace(escaped, (_m, ch) => ch));
+    }
+    return out.join('\n');
+}
+function renderTokens(tokens, ctx, out) {
+    for (const tok of tokens) {
+        switch (tok.type) {
+            case 'heading': {
+                const heading = tok;
+                const style = ctx.theme.styles['heading'];
+                const prefix = ' '.repeat(ctx.indent);
+                // Clean `## …` marker instead of the old solid-█ block.
+                const marker = `${'#'.repeat(Math.min(6, heading.depth))} `;
+                const text = renderInline(heading.tokens, ctx);
+                const raw = stripAnsiSimple(text);
+                const wrapped = wrapText(`${marker}${raw}`, ctx.width - ctx.indent);
+                for (const ln of wrapped) {
+                    out.push(`${prefix}${ctx.theme.table.sgr(style)}${ln}\x1b[0m`);
+                }
+                out.push('');
+                break;
+            }
+            case 'paragraph': {
+                const para = tok;
+                const text = renderInline(para.tokens, ctx);
+                const wrapped = wrapText(text, ctx.width - ctx.indent);
+                for (const ln of wrapped)
+                    out.push(`${' '.repeat(ctx.indent)}${ln}`);
+                out.push('');
+                break;
+            }
+            case 'space':
+                break;
+            case 'code': {
+                const code = tok;
+                const blockWidth = ctx.width - ctx.indent;
+                const langLabel = code.lang?.trim() ?? '';
+                const borderStyle = ctx.theme.styles['border'];
+                const borderSgr = ctx.theme.table.sgr(borderStyle);
+                const langStyle = ctx.theme.styles['accent'];
+                const codeBgStyle = ctx.theme.styles['codeBg'];
+                const codeBgSgr = ctx.theme.table.sgr(codeBgStyle);
+                const indent = ' '.repeat(ctx.indent);
+                // Top fence — centered language label (no stray backticks)
+                const label = langLabel ? ` ${langLabel} ` : '';
+                const dashes = Math.max(0, blockWidth - 2 - label.length);
+                const leftDashes = Math.floor(dashes / 2);
+                out.push(`${indent}${borderSgr}╭${'─'.repeat(leftDashes)}${langLabel ? `${ctx.theme.table.sgr(langStyle)}${label}\x1b[0m${borderSgr}` : ''}${'─'.repeat(dashes - leftDashes)}╮\x1b[0m`);
+                // Highlight. Known language: hljs. Otherwise plain text — avoids the
+                // slow auto-detect (tries every grammar) while streaming on mobile.
+                let ansiCode;
+                if (langLabel && hljs.getLanguage(langLabel)) {
+                    const highlighted = hljs.highlight(code.text, { language: langLabel }).value;
+                    ansiCode = htmlToAnsi(highlighted, ctx.theme);
+                }
+                else {
+                    ansiCode = code.text;
+                }
+                for (const ln of ansiCode.split('\n')) {
+                    const line = truncate(ln, blockWidth - 4, '…');
+                    out.push(`${indent}${borderSgr}│\x1b[0m${codeBgSgr} ${padRight(line, blockWidth - 4, ' ')} \x1b[0m${borderSgr}│\x1b[0m`);
+                }
+                // Bottom fence
+                out.push(`${indent}${borderSgr}╰${'─'.repeat(blockWidth - 2)}╯\x1b[0m`);
+                out.push('');
+                break;
+            }
+            case 'blockquote': {
+                const bq = tok;
+                const prevIndent = ctx.indent;
+                ctx.indent += 2;
+                renderTokens(bq.tokens, ctx, out);
+                ctx.indent = prevIndent;
+                break;
+            }
+            case 'list': {
+                const list = tok;
+                for (let idx = 0; idx < list.items.length; idx++) {
+                    const item = list.items[idx];
+                    let bullet = list.ordered
+                        ? `${ctx.indent + 1 + idx}.`
+                        : `${idx === 0 ? '▸' : '·'}`;
+                    let bulletStyle = ctx.theme.styles['muted'];
+                    let text = renderInline(item.tokens, ctx);
+                    // Checkbox tasks: drop the raw "[ ] / [x] " prefix and use a glyph,
+                    // checked → success, unchecked → dim.
+                    if (item.task) {
+                        text = text.replace(/^\[\s*?\][\s:]*/i, '').replace(/^\[[xX]\][\s:]*/, '');
+                        bullet = item.checked ? '☑' : '☐';
+                        bulletStyle = item.checked ? ctx.theme.styles['success'] : ctx.theme.styles['dim'];
+                    }
+                    const prevIndent = ctx.indent;
+                    ctx.indent += bullet.length + 1;
+                    const wrapped = wrapText(text, ctx.width - ctx.indent);
+                    out.push(`${' '.repeat(prevIndent)}${ctx.theme.table.sgr(bulletStyle)}${bullet}\x1b[0m ${wrapped[0] ?? ''}`);
+                    for (let i = 1; i < wrapped.length; i++)
+                        out.push(`${' '.repeat(ctx.indent)}${wrapped[i]}`);
+                    ctx.indent = prevIndent;
+                }
+                break;
+            }
+            case 'hr':
+                out.push(`${' '.repeat(ctx.indent)}${ctx.theme.table.sgr(ctx.theme.styles['line'])}${'─'.repeat(ctx.width - ctx.indent)}\x1b[0m`);
+                out.push('');
+                break;
+            case 'html':
+                break;
+            case 'table': {
+                renderTable(tok, ctx, out);
+                break;
+            }
+            default:
+                // fallback: render as plain text
+                out.push(`${' '.repeat(ctx.indent)}${tok.text ?? ''}`);
+                break;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Table rendering — bordered grid with per-column alignment.
+// ---------------------------------------------------------------------------
+function renderTable(table, ctx, out) {
+    const header = table.header;
+    const rows = table.rows;
+    const colCount = header.length;
+    const renderCell = (cell) => renderInline(cell.tokens, ctx);
+    const allCells = [header.map(renderCell), ...rows.map((r) => r.map(renderCell))];
+    // Column widths from visual width of content (strip ANSI when measuring).
+    const maxW = Math.max(8, ctx.width - ctx.indent);
+    let total = colCount * 3 + 1; // plus the extra border chars
+    const colWidths = [];
+    for (let c = 0; c < colCount; c++) {
+        let w = 1;
+        for (const row of allCells) {
+            const text = row[c] ?? '';
+            const vw = visWidth(stripAnsiText(text));
+            if (vw > w)
+                w = Math.min(maxW, vw);
+        }
+        colWidths.push(w);
+        total += w;
+    }
+    // If the table overflows the terminal, clamp columns proportionally.
+    if (total > maxW) {
+        const avail = maxW - (colCount * 3 + 1);
+        const scale = Math.max(0.15, avail / Math.max(1, total - (colCount * 3 + 1)));
+        let used = 0;
+        for (let c = 0; c < colCount; c++) {
+            colWidths[c] = Math.max(1, Math.floor(colWidths[c] * scale));
+            used += colWidths[c];
+        }
+        // distribute leftover width to the widest column
+        let slack = avail - used;
+        while (slack > 0) {
+            let maxIdx = 0;
+            for (let c = 1; c < colCount; c++)
+                if (colWidths[c] > colWidths[maxIdx])
+                    maxIdx = c;
+            colWidths[maxIdx] = colWidths[maxIdx] + 1;
+            slack--;
+        }
+    }
+    const border = ctx.theme.table.sgr(ctx.theme.styles['border']);
+    const heading = ctx.theme.table.sgr(ctx.theme.styles['heading']);
+    const reset = '\x1b[0m';
+    const indent = ' '.repeat(ctx.indent);
+    const W = (c) => colWidths[c] + 2; // content + 1 space each side
+    const horizontal = (left, mid, right) => {
+        let s = `${indent}${border}${left}`;
+        for (let c = 0; c < colCount; c++)
+            s += `${'─'.repeat(W(c))}${c < colCount - 1 ? mid : right}`;
+        out.push(`${s}${reset}`);
+    };
+    const cellLine = (row, isHeader) => {
+        const parts = [];
+        for (let c = 0; c < colCount; c++) {
+            const raw = truncate(row[c] ?? '', colWidths[c], '…');
+            const pad = Math.max(0, colWidths[c] - visWidth(stripAnsiText(raw)));
+            const align = table.align[c] ?? 'left';
+            let content = `${raw}${' '.repeat(pad)}`; // left (default)
+            if (align === 'right')
+                content = `${' '.repeat(pad)}${raw}`;
+            if (align === 'center') {
+                const l = Math.floor(pad / 2);
+                content = `${' '.repeat(l)}${raw}${' '.repeat(pad - l)}`;
+            }
+            parts.push(`${isHeader ? heading : ''} ${content} ${reset}`);
+        }
+        out.push(`${indent}${border}│${reset}${parts.join(`${border}│${reset}`)}${border}│${reset}`);
+    };
+    if (colCount > 0) {
+        horizontal('┌', '┬', '┐');
+        cellLine(header.map(renderCell), true);
+        horizontal('├', '┼', '┤');
+        for (const row of rows)
+            cellLine(row.map(renderCell), false);
+        horizontal('└', '┴', '┘');
+        out.push('');
+    }
+}
+function renderInline(tokens, ctx) {
+    return tokens.map((t) => renderInlineToken(t, ctx)).join('');
+}
+function renderInlineToken(tok, ctx) {
+    switch (tok.type) {
+        case 'text': {
+            const text = tok;
+            return text.text;
+        }
+        case 'codespan': {
+            const cs = tok;
+            return `${ctx.theme.table.sgr(ctx.theme.styles['inlineCode'])} ${cs.text} \x1b[0m`;
+        }
+        case 'strong':
+            return `${ctx.theme.table.sgr(ctx.theme.styles['bold'])}${renderInline(tok.tokens, ctx)}\x1b[0m`;
+        case 'em':
+            return `${ctx.theme.table.sgr(ctx.theme.styles['thinking'])}${renderInline(tok.tokens, ctx)}\x1b[0m`;
+        case 'del':
+            return `${ctx.theme.table.sgr(ctx.theme.styles['strike'])}${renderInline(tok.tokens, ctx)}\x1b[0m`;
+        case 'link': {
+            const link = tok;
+            return `${ctx.theme.table.sgr(ctx.theme.styles['link'])}${link.text}\x1b[0m`;
+        }
+        case 'image': {
+            const img = tok;
+            return img.text ? `[${img.text}]` : '[image]';
+        }
+        case 'br':
+            return '\n';
+        case 'escape':
+            return tok.text;
+        default:
+            return tok.text ?? '';
+    }
+}
+// ---------------------------------------------------------------------------
+// highlight.js HTML → ANSI
+// ---------------------------------------------------------------------------
+function htmlToAnsi(html, theme) {
+    // Map hljs CSS classes to theme style names.
+    const classMap = {
+        'hljs-keyword': theme.styles['accent'],
+        'hljs-built_in': theme.styles['info'],
+        'hljs-type': theme.styles['secondary'],
+        'hljs-literal': theme.styles['warning'],
+        'hljs-number': theme.styles['secondary'],
+        'hljs-string': theme.styles['success'],
+        'hljs-template-variable': theme.styles['success'],
+        'hljs-params': theme.styles['text'],
+        'hljs-function': theme.styles['info'],
+        'hljs-title': theme.styles['info'],
+        'hljs-title.function_': theme.styles['info'],
+        'hljs-title.class_': theme.styles['secondary'],
+        'hljs-variable': theme.styles['text'],
+        'hljs-comment': theme.styles['muted'],
+        'hljs-doctag': theme.styles['muted'],
+        'hljs-meta': theme.styles['muted'],
+        'hljs-tag': theme.styles['danger'],
+        'hljs-name': theme.styles['danger'],
+        'hljs-attr': theme.styles['warning'],
+        'hljs-selector-id': theme.styles['info'],
+        'hljs-selector-class': theme.styles['info'],
+        'hljs-regexp': theme.styles['warning'],
+        'hljs-symbol': theme.styles['warning'],
+        'hljs-property': theme.styles['info'],
+        'hljs-operator': theme.styles['muted'],
+        'hljs-punctuation': theme.styles['muted'],
+        'hljs-meta.hljs-string': theme.styles['success'],
+    };
+    const RESET = '\x1b[0m';
+    let out = '';
+    let i = 0;
+    while (i < html.length) {
+        if (html[i] !== '<') {
+            let end = html.indexOf('<', i);
+            if (end === -1)
+                end = html.length;
+            out += decodeEntities(html.slice(i, end));
+            i = end;
+            continue;
+        }
+        // Parse opening tag
+        const tagStart = i;
+        const tagEnd = html.indexOf('>', i);
+        if (tagEnd === -1) {
+            out += decodeEntities(html.slice(i));
+            break;
+        }
+        const tag = html.slice(i, tagEnd + 1);
+        i = tagEnd + 1;
+        if (tag.startsWith('<span')) {
+            const classMatch = tag.match(/class="([^"]+)"/);
+            if (classMatch) {
+                const cls = classMatch[1];
+                const styleId = classMap[cls];
+                if (styleId != null) {
+                    out += theme.table.sgr(styleId);
+                }
+            }
+        }
+        else if (tag === '</span>') {
+            out += RESET;
+        }
+    }
+    return out;
+}
+function stripAnsiSimple(s) {
+    return s.replace(/\x1b\[[0-9;]*m/g, '');
+}
+/** Decode HTML entities emitted by highlight.js into plain characters. */
+function decodeEntities(src) {
+    if (!src.includes('&'))
+        return src;
+    const named = {
+        amp: '&',
+        lt: '<',
+        gt: '>',
+        quot: '"',
+        apos: "'",
+        nbsp: ' ',
+        bull: '•',
+        hellip: '…',
+        mdash: '—',
+        ndash: '–',
+        lsquo: '‘',
+        rsquo: '’',
+        ldquo: '“',
+        rdquo: '”',
+        middot: '·',
+    };
+    return src.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (m, body) => {
+        if (body[0] === '#') {
+            const hex = body[1] === 'x' || body[1] === 'X';
+            const n = parseInt(body.slice(hex ? 2 : 1), hex ? 16 : 10);
+            if (!Number.isNaN(n) && n >= 0 && n <= 0x10ffff) {
+                try {
+                    return String.fromCodePoint(n);
+                }
+                catch {
+                    return m;
+                }
+            }
+            return m;
+        }
+        return named[body] ?? m;
+    });
+}

package/dist/src/tui/components/message.js

@@ -0,0 +1,105 @@
+import { wrapText, truncate, padRight, width as sw } from '../text.js';
+import { renderMarkdown } from './markdown.js';
+export function messageToLines(msg, theme, width, opts = {}) {
+    if (msg.role === 'user')
+        return renderUser(msg, theme, width, opts);
+    if (msg.role === 'assistant')
+        return renderAssistant(msg, theme, width, opts);
+    if (msg.role === 'system')
+        return renderSystem(msg, theme, width, opts);
+    return renderUser({ ...msg, content: `[${msg.role}] ${msg.content}` }, theme, width, opts);
+}
+function renderUser(msg, theme, width, _opts) {
+    const lines = [];
+    const accentSgr = theme.table.sgr(theme.styles['accent']);
+    const dimSgr = theme.table.sgr(theme.styles['dim']);
+    const reset = '\x1b[0m';
+    lines.push(`${accentSgr}❯ you${reset}`);
+    const body = wrapText(msg.content, Math.max(8, width - 4));
+    for (const ln of body) {
+        lines.push(`${dimSgr} │${reset} ${ln}`);
+    }
+    return lines;
+}
+function renderAssistant(msg, theme, width, opts) {
+    const lines = [];
+    const reset = '\x1b[0m';
+    const accentSgr = theme.table.sgr(theme.styles['accent']);
+    const mutedSgr = theme.table.sgr(theme.styles['muted']);
+    const dimSgr = theme.table.sgr(theme.styles['dim']);
+    const modelLabel = msg.model ? ` · ${msg.model}` : '';
+    lines.push(`${accentSgr}◈ orbit${reset}${mutedSgr}${modelLabel}${reset}`);
+    // Thinking block — collapsed by default unless enabled in config.
+    if (msg.reasoning && msg.reasoning.length > 0) {
+        const open = opts.thinkingDefaultOpen ?? msg.reasoningOpen ?? false;
+        const tokenCount = tokenEstimate(msg.reasoning);
+        const indicator = open ? '▾' : '▸';
+        lines.push(`${mutedSgr}${indicator} thinking · ~${tokenCount} tokens (press t)${reset}`);
+        if (open) {
+            const wrapped = wrapText(msg.reasoning, Math.max(8, width - 6));
+            for (const ln of wrapped) {
+                lines.push(`${mutedSgr}  ${ln}${reset}`);
+            }
+        }
+    }
+    // Content
+    if (msg.content) {
+        const md = renderMarkdown(msg.content, { theme, width: Math.max(8, width - 4) });
+        for (const ln of md)
+            lines.push(`${ln}`);
+    }
+    // Tool calls
+    if (msg.toolCalls && msg.toolCalls.length > 0) {
+        for (const tc of msg.toolCalls) {
+            lines.push(...toolCardToLines(tc, theme, width));
+        }
+    }
+    // Streaming indicator
+    if (msg.streaming) {
+        lines.push(`${dimSgr}…${reset}`);
+    }
+    return lines;
+}
+function toolCardToLines(tc, theme, width) {
+    const lines = [];
+    const reset = '\x1b[0m';
+    const statusIcon = tc.status === 'done'
+        ? `${theme.table.sgr(theme.styles['toolDone'])}✓`
+        : tc.status === 'error'
+            ? `${theme.table.sgr(theme.styles['toolError'])}✗`
+            : tc.status === 'running'
+                ? `${theme.table.sgr(theme.styles['toolRunning'])}⠋`
+                : `${theme.table.sgr(theme.styles['toolPending'])}○`;
+    const durationStr = tc.durationMs != null ? `${tc.durationMs}ms` : '';
+    const name = truncate(tc.name, Math.max(4, width - 14), '…');
+    const innerW = Math.max(2, width - 4);
+    const topLeft = `${statusIcon} ${name}${reset}`;
+    const topRight = `${theme.table.sgr(theme.styles['muted'])}${durationStr}${reset}`;
+    const borderSgr = theme.table.sgr(theme.styles['border']);
+    const topText = `┌ ${topLeft}${' '.repeat(Math.max(0, innerW - sw(topLeft) - sw(topRight) - 2))}${topRight}`;
+    lines.push(`${borderSgr}${topText} ┐${reset}`);
+    // Args preview
+    const args = truncate(tc.args, Math.max(4, innerW - 2), '…');
+    lines.push(`${borderSgr}│${reset} ${theme.table.sgr(theme.styles['muted'])}${args}${reset}`);
+    // Result preview
+    if (tc.result) {
+        const preview = truncate(tc.result, Math.max(4, innerW - 2), '…');
+        lines.push(`${borderSgr}│${reset} ${preview}`);
+    }
+    lines.push(`${borderSgr}└${padRight('', innerW, '─')}┘${reset}`);
+    return lines;
+}
+function renderSystem(msg, theme, width, _opts) {
+    const mutedSgr = theme.table.sgr(theme.styles['info']);
+    const reset = '\x1b[0m';
+    const wrapped = wrapText(msg.content, Math.max(8, width - 6));
+    const out = [`${mutedSgr}ℹ ${wrapped[0] ?? ''}${reset}`];
+    for (let i = 1; i < wrapped.length; i++)
+        out.push(`${mutedSgr}  ${wrapped[i]}${reset}`);
+    return out;
+}
+function tokenEstimate(text) {
+    const n = Math.ceil(text.length / 4);
+    return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : `${n}`;
+}
+export { truncate, wrapText };

package/dist/src/tui/context.js

@@ -0,0 +1,8 @@
+import { createContext, useContext } from 'react';
+export const StoreContext = createContext(null);
+export function useStore() {
+    const store = useContext(StoreContext);
+    if (!store)
+        throw new Error('Orbit Ink components must be rendered inside the store context');
+    return store;
+}

package/dist/src/tui/geometry.js

@@ -0,0 +1,40 @@
+import { wrapText } from './text.js';
+/**
+ * Deterministic layout numbers for the fixed-height chrome around the
+ * transcript. Terminal row budget = sum of these; the transcript gets the rest.
+ */
+export const HEADER_H = 4; // boxed header: border(1+1) + 2 content rows
+export const TIP_H = 1;
+export const SEP_H = 1;
+export const STATUS_H = 1;
+export const WORKING_H = 1;
+/** In-flow permission panel height (border 2 + 3 content rows). */
+export const ASK_H = 5;
+/** Visual line count of the composer input (soft wraps included). */
+export function composerVisualLines(input, width) {
+    const contentW = Math.max(1, width - 2);
+    let n = 0;
+    for (const line of input.lines) {
+        if (line === '')
+            n += 1;
+        else
+            n += wrapText(line, contentW).length;
+    }
+    return Math.max(1, n);
+}
+/** Rendered composer box height, clamped to [1, 4] rows. */
+export function composerHeight(input, width) {
+    return Math.min(4, Math.max(1, composerVisualLines(input, width)));
+}
+export function chromeHeight(args) {
+    return (HEADER_H +
+        TIP_H +
+        (args.working ? WORKING_H : 0) +
+        (args.ask ? ASK_H : 0) +
+        args.menuLines +
+        args.modelLines +
+        args.dockLines +
+        SEP_H +
+        args.composerH +
+        STATUS_H);
+}

package/dist/src/tui/renderer.js

@@ -0,0 +1,116 @@
+/**
+ * Line-oriented render surface.
+ *
+ * Replaces the old per-cell Screen/blit pipeline with a much simpler model:
+ * every frame, components produce one fully-styled string per terminal row,
+ * each row carries the theme background baked into its own SGR spans, and the
+ * flusher only repaints rows whose text actually changed. This keeps streaming
+ * updates cheap and — critically — never leaves half-cleared rows visible, so
+ * there is no more duplicated/overlapping text or terminal-default backgrounds.
+ */
+import stringWidth from 'string-width';
+import stripAnsi from 'strip-ansi';
+import { RESET } from './style.js';
+import { write } from './term.js';
+export class VTerm {
+    w;
+    h;
+    rows;
+    prev;
+    dirtyFlags;
+    constructor(w, h) {
+        this.w = w;
+        this.h = h;
+        this.rows = new Array(h).fill('');
+        this.prev = new Array(h).fill('\u0000');
+        this.dirtyFlags = new Array(h).fill(false);
+    }
+    resize(w, h) {
+        if (w === this.w && h === this.h)
+            return;
+        this.w = w;
+        this.h = h;
+        this.rows = new Array(h).fill('');
+        // Force a full repaint after resize.
+        this.prev = new Array(h).fill('\u0000');
+        this.dirtyFlags = new Array(h).fill(true);
+    }
+    /** Clear every row to empty (next flush repaints them). */
+    reset() {
+        this.rows = new Array(this.h).fill('');
+        for (let y = 0; y < this.h; y++)
+            this.dirtyFlags[y] = true;
+    }
+    setRow(y, line) {
+        if (y < 0 || y >= this.h)
+            return;
+        if (this.rows[y] === line)
+            return;
+        this.rows[y] = line;
+        this.dirtyFlags[y] = true;
+    }
+    /** Paint a region clear using the theme background, marking changed rows. */
+    fillClear(theme) {
+        const bg = theme.table.sgr(theme.styles['bg']);
+        const pad = theme.table.sgr(theme.styles['pad']);
+        const blank = `${bg}${pad}${' '.repeat(this.w)}${RESET}`;
+        for (let y = 0; y < this.h; y++)
+            this.setRow(y, blank);
+    }
+    flushLines() {
+        let out = '';
+        for (let y = 0; y < this.h; y++) {
+            if (!this.dirtyFlags[y])
+                continue;
+            const row = this.rows[y] ?? '';
+            // Length-guard: if a row overflows the terminal width it would wrap and
+            // desync subsequent rows, so clip to the field width (keeps SGRs intact
+            // because composeRow appends padding only when the row fits).
+            out += `\x1b[${y + 1};1H${row}`;
+            this.prev[y] = row;
+            this.dirtyFlags[y] = false;
+        }
+        return out;
+    }
+    /** Flush dirty rows to the terminal. Returns false when nothing changed. */
+    flush() {
+        if (!this.dirtyFlags.some(Boolean))
+            return false;
+        const out = this.flushLines();
+        if (out.length > 0)
+            write(out);
+        return true;
+    }
+}
+/**
+ * Assemble one terminal row: paint the theme background behind the entire
+ * content, re-assert it after every embedded SGR reset, then pad to `width`
+ * with the background so trailing cells are always the theme color.
+ */
+export function composeRow(theme, width, content) {
+    const bg = theme.table.sgr(theme.styles['bg']);
+    const pad = theme.table.sgr(theme.styles['pad']);
+    const contentW = stringWidth(stripAnsi(content));
+    // Re-apply the background after every reset so unstyled gaps never show the
+    // terminal default background mid-row.
+    const safe = `${bg}${content.replace(/\x1b\[0m/g, `${RESET}${bg}`)}`;
+    const padLen = Math.max(0, width - contentW);
+    if (padLen === 0)
+        return `${safe}${RESET}`;
+    return `${safe}${pad}${' '.repeat(padLen)}${RESET}`;
+}
+/** A fully background-filled, empty row (used at startup / resize). */
+export function blankRow(theme, width) {
+    return composeRow(theme, width, '');
+}
+/** Center `content` horizontally on a full-width row. */
+export function centerRow(theme, width, content) {
+    const w = stringWidth(stripAnsi(content));
+    const side = Math.max(0, Math.floor((width - w) / 2));
+    return composeRow(theme, width, `${' '.repeat(side)}${content}`);
+}
+/** A subtle horizontal rule in the border color. */
+export function ruleRow(theme, width, char = '─') {
+    const border = theme.table.sgr(theme.styles['border']);
+    return composeRow(theme, width, `${border}${char.repeat(width)}\x1b[0m`);
+}