@askalf/dario 3.38.5 → 4.0.0

package/dist/tui/app.js

@@ -0,0 +1,178 @@
+/**
+ * The TUI App — main render loop + lifecycle + key dispatch.
+ *
+ * The shape is deliberately simple: one render function (caller-
+ * supplied) that takes `state + dimensions` and returns the full frame
+ * as a string. The App drives the loop, manages stdin raw mode, handles
+ * resize events, and flushes one write per frame. Tabs (M4) are
+ * decoupled state machines that the caller's render() composes.
+ *
+ * Lifecycle invariants:
+ *
+ *   - Enters alt-screen on start, leaves on stop. The shell that
+ *     spawned dario sees its prior content restored when the TUI quits.
+ *   - Hides the cursor on start, restores it on stop. ALWAYS, even on
+ *     uncaught exceptions or SIGINT — we install signal + exit hooks.
+ *   - Sets stdin raw mode on start, restores it on stop.
+ *
+ * The hook chain is registered on process events; quit calls them all
+ * synchronously so no terminal state leaks out.
+ */
+import { attachKeyHandler } from './input.js';
+import { clearScreen, enterAltScreen, leaveAltScreen, hideCursor, showCursor, } from './render.js';
+export class App {
+    state;
+    renderFn;
+    keyFn;
+    afterFrameFn;
+    stdin;
+    stdout;
+    cleanupFns = [];
+    running = false;
+    // Coalesce setState calls that arrive in the same tick — only one
+    // redraw per tick regardless of how many setStates fire.
+    redrawScheduled = false;
+    constructor(opts) {
+        this.state = opts.initialState;
+        this.renderFn = opts.render;
+        this.keyFn = opts.onKey;
+        this.afterFrameFn = opts.afterFrame;
+        this.stdin = opts.stdin ?? process.stdin;
+        this.stdout = opts.stdout ?? process.stdout;
+    }
+    /**
+     * Replace state. If the new state differs from the old (shallow
+     * equality), schedule a redraw. Tabs use this both for synchronous
+     * key-driven updates and for async data arrivals (SSE 'record').
+     *
+     * The "differs" check is intentionally shallow — deep equality on
+     * potentially-large analytics records would be expensive and the
+     * caller almost always passes new object identity when it mutates.
+     * If you mutate state in place and don't change identity, the
+     * redraw won't fire (this is documented; sometimes desired).
+     */
+    setState(updater) {
+        const next = typeof updater === 'function'
+            ? updater(this.state)
+            : { ...this.state, ...updater };
+        if (next !== this.state) {
+            this.state = next;
+            this.scheduleRedraw();
+        }
+    }
+    /** Read-only state accessor — for callers that need to compute next state from current. */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Start the TUI: enter alt-screen, hide cursor, raw stdin, attach
+     * resize listener, render once, then idle until stop() or process
+     * exit.
+     *
+     * Returns a Promise that resolves when stop() is called. Wires
+     * process exit / signal hooks so a Ctrl-C / kill leaves the
+     * terminal sane.
+     */
+    start() {
+        if (this.running)
+            throw new Error('TUI already running');
+        this.running = true;
+        // Enter alt-screen + hide cursor in one write so the terminal
+        // doesn't briefly show a normal screen with a hidden cursor.
+        this.stdout.write(enterAltScreen + hideCursor + clearScreen);
+        // Raw-mode key handler
+        try {
+            const detachKeys = attachKeyHandler(this.stdin, (key) => {
+                // Global keys handled by the App itself; everything else
+                // falls through to the user's onKey reducer.
+                if (key.name === 'printable' && key.ctrl && key.ch === 'c') {
+                    // Ctrl-C → quit
+                    this.stop();
+                    return;
+                }
+                if (key.name === 'printable' && key.ctrl && key.ch === 'l') {
+                    // Ctrl-L → forced redraw (no state change, but force a
+                    // re-render which also re-clears the screen — clears any
+                    // garbage left by misbehaving processes that wrote past the
+                    // alt-screen boundary)
+                    this.scheduleRedraw(true);
+                    return;
+                }
+                const next = this.keyFn(this.state, key);
+                if (next !== undefined && next !== this.state) {
+                    this.state = next;
+                    this.scheduleRedraw();
+                }
+            });
+            this.cleanupFns.push(detachKeys);
+        }
+        catch (err) {
+            // Couldn't attach to stdin (not a TTY). Restore screen state
+            // before propagating so we don't leave the terminal in
+            // alt-screen mode.
+            this.stdout.write(leaveAltScreen + showCursor);
+            this.running = false;
+            throw err;
+        }
+        // Window resize → redraw with new dimensions
+        const onResize = () => this.scheduleRedraw(true);
+        this.stdout.on('resize', onResize);
+        this.cleanupFns.push(() => this.stdout.off('resize', onResize));
+        // Process-level safety net — any abnormal exit should leave the
+        // terminal in a usable state.
+        const finalCleanup = () => {
+            if (this.running)
+                this.stop();
+        };
+        process.once('SIGINT', finalCleanup);
+        process.once('SIGTERM', finalCleanup);
+        process.once('exit', finalCleanup);
+        this.cleanupFns.push(() => {
+            process.off('SIGINT', finalCleanup);
+            process.off('SIGTERM', finalCleanup);
+            process.off('exit', finalCleanup);
+        });
+        // First frame
+        this.redraw();
+        return new Promise((resolve) => {
+            this.cleanupFns.push(() => resolve());
+        });
+    }
+    /** Stop the TUI — restore terminal state and resolve the start() promise. */
+    stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        // Run cleanup fns in reverse order so most-recent goes first
+        // (matches typical resource-stack semantics).
+        while (this.cleanupFns.length > 0) {
+            const fn = this.cleanupFns.pop();
+            try {
+                fn();
+            }
+            catch { /* keep unwinding */ }
+        }
+        // Final state restore
+        this.stdout.write(leaveAltScreen + showCursor);
+    }
+    scheduleRedraw(force = false) {
+        if (this.redrawScheduled && !force)
+            return;
+        this.redrawScheduled = true;
+        queueMicrotask(() => {
+            this.redrawScheduled = false;
+            if (!this.running)
+                return;
+            this.redraw();
+        });
+    }
+    redraw() {
+        const cols = this.stdout.columns ?? 80;
+        const rows = this.stdout.rows ?? 24;
+        const frame = this.renderFn(this.state, { cols, rows });
+        // Single write — minimizes flicker
+        this.stdout.write(clearScreen + frame);
+        if (this.afterFrameFn)
+            this.afterFrameFn(this.state);
+    }
+}

package/dist/tui/input.d.ts

@@ -0,0 +1,57 @@
+/**
+ * TUI input handling — stdin raw-mode key parser.
+ *
+ * Why not Node's `readline.emitKeypressEvents`: it works, but the Key
+ * shape (`{ name, ctrl, meta, sequence }`) is loosely typed, the
+ * legacy event flag is awkward to disable cleanly, and its escape-
+ * sequence parser has historically lagged on edge cases (Windows
+ * Terminal modifyOtherKeys, Kitty progressive enhancement, etc).
+ *
+ * Writing ~150 lines that handle the keys we ACTUALLY use is more
+ * predictable. The keys we care about:
+ *
+ *   - Printable ASCII (0x20-0x7e)
+ *   - Enter, Tab, Backspace, Escape
+ *   - Arrow up/down/left/right
+ *   - Home, End, PgUp, PgDn
+ *   - Ctrl+C, Ctrl+D (exit), Ctrl+L (redraw)
+ *
+ * Standalone Esc vs Esc-led sequence (e.g. arrow): we use the same
+ * heuristic xterm uses — if ESC arrives in the same buffer chunk as
+ * subsequent bytes, treat as a CSI sequence. If ESC arrives alone in
+ * a chunk, treat as a standalone Escape keypress. This is reliable
+ * on real terminals and avoids the alternative (a wait-timer + lookahead)
+ * which adds complexity and a delay every Esc keypress.
+ */
+export interface Key {
+    /** A short name for the key. 'printable' for normal characters. */
+    name: 'printable' | 'enter' | 'tab' | 'backspace' | 'escape' | 'up' | 'down' | 'left' | 'right' | 'home' | 'end' | 'pageup' | 'pagedown' | 'delete' | 'unknown';
+    /** The printable character (or the raw sequence for `unknown`). */
+    ch: string;
+    /** True if a Ctrl modifier was held. */
+    ctrl: boolean;
+    /** True if a Shift modifier was held (only detectable on some keys). */
+    shift: boolean;
+    /** True if an Alt/Meta modifier was held. */
+    meta: boolean;
+}
+/**
+ * Parse one stdin chunk into zero or more Key events. Pure function;
+ * the caller drives stdin and accumulates the result. Most chunks
+ * yield exactly one key (interactive typing); paste / IME burst can
+ * yield several.
+ */
+export declare function parseKeys(chunk: Buffer): Key[];
+/**
+ * Put stdin into raw mode and start emitting Key events to `handler`.
+ * Returns a cleanup function that restores stdin's pre-raw mode and
+ * unbinds the listener. ALWAYS call the cleanup on exit (including
+ * abnormal exits — wire a process exit / signal hook).
+ *
+ * Defaults are picked so the caller doesn't have to think about them:
+ * UTF-8 encoding (we don't see Buffer chunks split mid-character),
+ * resume() so paused stdin doesn't drop key events.
+ *
+ * Throws if stdin isn't a TTY — the TUI doesn't make sense in a pipe.
+ */
+export declare function attachKeyHandler(stdin: NodeJS.ReadStream, handler: (key: Key) => void): () => void;

package/dist/tui/input.js

@@ -0,0 +1,206 @@
+/**
+ * TUI input handling — stdin raw-mode key parser.
+ *
+ * Why not Node's `readline.emitKeypressEvents`: it works, but the Key
+ * shape (`{ name, ctrl, meta, sequence }`) is loosely typed, the
+ * legacy event flag is awkward to disable cleanly, and its escape-
+ * sequence parser has historically lagged on edge cases (Windows
+ * Terminal modifyOtherKeys, Kitty progressive enhancement, etc).
+ *
+ * Writing ~150 lines that handle the keys we ACTUALLY use is more
+ * predictable. The keys we care about:
+ *
+ *   - Printable ASCII (0x20-0x7e)
+ *   - Enter, Tab, Backspace, Escape
+ *   - Arrow up/down/left/right
+ *   - Home, End, PgUp, PgDn
+ *   - Ctrl+C, Ctrl+D (exit), Ctrl+L (redraw)
+ *
+ * Standalone Esc vs Esc-led sequence (e.g. arrow): we use the same
+ * heuristic xterm uses — if ESC arrives in the same buffer chunk as
+ * subsequent bytes, treat as a CSI sequence. If ESC arrives alone in
+ * a chunk, treat as a standalone Escape keypress. This is reliable
+ * on real terminals and avoids the alternative (a wait-timer + lookahead)
+ * which adds complexity and a delay every Esc keypress.
+ */
+/**
+ * Parse one stdin chunk into zero or more Key events. Pure function;
+ * the caller drives stdin and accumulates the result. Most chunks
+ * yield exactly one key (interactive typing); paste / IME burst can
+ * yield several.
+ */
+export function parseKeys(chunk) {
+    const keys = [];
+    let i = 0;
+    while (i < chunk.length) {
+        const b = chunk[i];
+        // Backspace: ASCII 0x7f on most terminals, 0x08 (BS / Ctrl+H) on
+        // Windows console + a few older ttys. Must check 0x08 BEFORE the
+        // Ctrl+letter range below, otherwise BS gets reported as Ctrl+H.
+        if (b === 0x7f || b === 0x08) {
+            keys.push(k('backspace', ''));
+            i++;
+            continue;
+        }
+        // Control keys (Ctrl+letter): byte 0x01-0x1a (A-Z masked with 0x1f)
+        if (b >= 0x01 && b <= 0x1a) {
+            // Special-case the named ones that aren't really "Ctrl+letter".
+            if (b === 0x09) {
+                keys.push(k('tab', '\t'));
+                i++;
+                continue;
+            }
+            if (b === 0x0a || b === 0x0d) {
+                keys.push(k('enter', '\n'));
+                i++;
+                continue;
+            }
+            // The rest are Ctrl+A through Ctrl+Z (skipping the named ones).
+            keys.push({
+                name: 'printable', ch: String.fromCharCode(b + 96), // 1 → 'a'
+                ctrl: true, shift: false, meta: false,
+            });
+            i++;
+            continue;
+        }
+        // Escape — either standalone or the start of a CSI sequence.
+        if (b === 0x1b) {
+            // Look at what follows in this same chunk
+            if (i + 1 >= chunk.length) {
+                // ESC alone in this chunk → standalone Escape keypress.
+                keys.push(k('escape', ''));
+                i++;
+                continue;
+            }
+            // ESC + '[' → CSI sequence. Read up to the terminating byte
+            // (0x40-0x7e per ECMA-48).
+            if (chunk[i + 1] === 0x5b /* '[' */ || chunk[i + 1] === 0x4f /* 'O' for SS3 */) {
+                const seqStart = i;
+                const ss3 = chunk[i + 1] === 0x4f;
+                i += 2;
+                let paramBytes = '';
+                while (i < chunk.length) {
+                    const c = chunk[i];
+                    if (c >= 0x40 && c <= 0x7e) {
+                        const final = String.fromCharCode(c);
+                        i++;
+                        keys.push(parseCsi(final, paramBytes, ss3, chunk.slice(seqStart, i)));
+                        break;
+                    }
+                    paramBytes += String.fromCharCode(c);
+                    i++;
+                }
+                continue;
+            }
+            // ESC + other byte → Alt/Meta + that byte
+            const next = chunk[i + 1];
+            if (next >= 0x20 && next <= 0x7e) {
+                keys.push({
+                    name: 'printable', ch: String.fromCharCode(next),
+                    ctrl: false, shift: false, meta: true,
+                });
+                i += 2;
+                continue;
+            }
+            // Fallback — emit ESC alone, advance one.
+            keys.push(k('escape', ''));
+            i++;
+            continue;
+        }
+        // Printable ASCII (including space)
+        if (b >= 0x20 && b <= 0x7e) {
+            keys.push({
+                name: 'printable', ch: String.fromCharCode(b),
+                ctrl: false, shift: b >= 0x41 && b <= 0x5a, meta: false,
+            });
+            i++;
+            continue;
+        }
+        // Anything else — pass through as unknown so the caller can see it.
+        keys.push({ name: 'unknown', ch: String.fromCharCode(b), ctrl: false, shift: false, meta: false });
+        i++;
+    }
+    return keys;
+}
+function k(name, ch) {
+    return { name, ch, ctrl: false, shift: false, meta: false };
+}
+/**
+ * Decode the body of a CSI sequence given the terminating byte and
+ * the parameter bytes between `[` and the terminator.
+ *
+ *   ESC[A    → up
+ *   ESC[B    → down
+ *   ESC[C    → right
+ *   ESC[D    → left
+ *   ESC[H    → home
+ *   ESC[F    → end
+ *   ESC[5~   → pageup
+ *   ESC[6~   → pagedown
+ *   ESC[3~   → delete
+ *   ESC[1~   → home (alternate)
+ *   ESC[4~   → end (alternate)
+ *
+ * Modifier-bearing variants (e.g. `ESC[1;5A` for Ctrl-Up) parse the
+ * second parameter as a modifier mask: bit 0 = Shift, bit 1 = Alt,
+ * bit 2 = Ctrl. xterm spec §"Modifier-Encoding".
+ */
+function parseCsi(final, params, ss3, raw) {
+    // Parse semicolon-separated numeric params
+    const parts = params.split(';').map(p => parseInt(p, 10) || 0);
+    // Modifier byte is the second param when present.
+    const mod = parts[1] ?? 1;
+    const ctrl = (mod - 1) & 4 ? true : false;
+    const shift = (mod - 1) & 1 ? true : false;
+    const meta = (mod - 1) & 2 ? true : false;
+    // Tilde-terminated: ESC[<n>~ where n is in parts[0]
+    if (final === '~') {
+        const n = parts[0];
+        const map = {
+            1: 'home', 2: 'home', 3: 'delete', 4: 'end',
+            5: 'pageup', 6: 'pagedown', 7: 'home', 8: 'end',
+        };
+        return { name: map[n] ?? 'unknown', ch: raw.toString(), ctrl, shift, meta };
+    }
+    // Letter-terminated: arrow / home / end (and SS3 variants)
+    void ss3;
+    const letterMap = {
+        A: 'up', B: 'down', C: 'right', D: 'left',
+        H: 'home', F: 'end',
+    };
+    if (letterMap[final]) {
+        return { name: letterMap[final], ch: raw.toString(), ctrl, shift, meta };
+    }
+    return { name: 'unknown', ch: raw.toString(), ctrl, shift, meta };
+}
+// ── Lifecycle helpers ──────────────────────────────────────────────
+/**
+ * Put stdin into raw mode and start emitting Key events to `handler`.
+ * Returns a cleanup function that restores stdin's pre-raw mode and
+ * unbinds the listener. ALWAYS call the cleanup on exit (including
+ * abnormal exits — wire a process exit / signal hook).
+ *
+ * Defaults are picked so the caller doesn't have to think about them:
+ * UTF-8 encoding (we don't see Buffer chunks split mid-character),
+ * resume() so paused stdin doesn't drop key events.
+ *
+ * Throws if stdin isn't a TTY — the TUI doesn't make sense in a pipe.
+ */
+export function attachKeyHandler(stdin, handler) {
+    if (!stdin.isTTY) {
+        throw new Error('TUI requires a TTY on stdin — pipe / redirect not supported');
+    }
+    const prevRawMode = stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    const onData = (chunk) => {
+        for (const key of parseKeys(chunk))
+            handler(key);
+    };
+    stdin.on('data', onData);
+    return () => {
+        stdin.off('data', onData);
+        stdin.setRawMode(prevRawMode ?? false);
+        stdin.pause();
+    };
+}

package/dist/tui/layout.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Higher-level layout primitives built on top of `render.ts`.
+ *
+ * These compose the lower-level ANSI strings into the structural
+ * patterns the v4 TUI actually uses: a header bar, a tab strip,
+ * a body region, a footer with key hints. Each returns a string
+ * (or appends to a Frame) — no terminal state, no side effects.
+ */
+/**
+ * Render the top header bar: brand + version on the left, contextual
+ * status text on the right (e.g. proxy URL when connected).
+ *
+ *   ╭ dario v4.0.0 ───────────────────── http://localhost:3456 ─╮
+ *
+ * Width is the full terminal columns; the caller positions it at row 1.
+ */
+export declare function renderHeader(width: number, opts: {
+    version: string;
+    status?: string;
+}): string;
+/**
+ * Render the bottom footer with key-hint pairs. Wide gaps so it doesn't
+ * look mashed-together:
+ *
+ *   [Tab] switch panel   [q] quit   [?] help
+ */
+export declare function renderFooter(width: number, hints: Array<{
+    key: string;
+    label: string;
+}>): string;
+/**
+ * Render a tab strip — one row of clickable-looking tab labels, with
+ * the active tab inverse-highlighted. Borders flank both sides.
+ *
+ *   │  Status   ▎Analytics▎   Config   Hits   Accounts   Backends   │
+ *
+ * The `activeTab` is the index of the highlighted tab. Caller draws
+ * the surrounding box separately.
+ */
+export declare function renderTabStrip(width: number, tabs: string[], activeTab: number): string;
+/**
+ * Render a vertical scroll indicator on the right edge of a panel.
+ * Shows "n / total" + a position blob if there's overflow.
+ *
+ *   ─ 24 / 412
+ */
+export declare function renderScrollIndicator(visible: number, total: number, selectedIdx: number): string;
+/**
+ * Word-wrap or hard-break `text` to lines of at most `width` visible
+ * chars. ANSI sequences are preserved across line boundaries; visible
+ * width is what's counted.
+ *
+ * Used for free-form prose in the Status / About panels.
+ */
+export declare function wrap(text: string, width: number): string[];
+/**
+ * Render a left-key / right-value row (the shape every config/status
+ * line uses).
+ *
+ *   Port:               3456
+ *   Mode:               passthrough
+ *
+ * Key is left-padded to `keyWidth` so a column of rows aligns. Value
+ * is truncated to fit the remaining space.
+ */
+export declare function renderKvRow(key: string, value: string, totalWidth: number, keyWidth?: number): string;

package/dist/tui/layout.js

@@ -0,0 +1,152 @@
+/**
+ * Higher-level layout primitives built on top of `render.ts`.
+ *
+ * These compose the lower-level ANSI strings into the structural
+ * patterns the v4 TUI actually uses: a header bar, a tab strip,
+ * a body region, a footer with key hints. Each returns a string
+ * (or appends to a Frame) — no terminal state, no side effects.
+ */
+import { brand, fg, inverse, BOX, pad, truncate, visibleWidth } from './render.js';
+/**
+ * Render the top header bar: brand + version on the left, contextual
+ * status text on the right (e.g. proxy URL when connected).
+ *
+ *   ╭ dario v4.0.0 ───────────────────── http://localhost:3456 ─╮
+ *
+ * Width is the full terminal columns; the caller positions it at row 1.
+ */
+export function renderHeader(width, opts) {
+    const left = ` ${brand('dario')} v${opts.version} `;
+    const right = opts.status ? ` ${opts.status} ` : '';
+    const dashWidth = Math.max(0, width - visibleWidth(left) - visibleWidth(right) - 2);
+    return BOX.topLeft + left + BOX.horizontal.repeat(dashWidth) + right + BOX.topRight;
+}
+/**
+ * Render the bottom footer with key-hint pairs. Wide gaps so it doesn't
+ * look mashed-together:
+ *
+ *   [Tab] switch panel   [q] quit   [?] help
+ */
+export function renderFooter(width, hints) {
+    const items = hints.map(h => `${fg('cyan', `[${h.key}]`)} ${h.label}`);
+    const joined = items.join('   ');
+    // Truncate if the hints don't fit (small terminal); never wrap to a
+    // second line — the footer is a single row by design.
+    return ' ' + truncate(joined, width - 2);
+}
+/**
+ * Render a tab strip — one row of clickable-looking tab labels, with
+ * the active tab inverse-highlighted. Borders flank both sides.
+ *
+ *   │  Status   ▎Analytics▎   Config   Hits   Accounts   Backends   │
+ *
+ * The `activeTab` is the index of the highlighted tab. Caller draws
+ * the surrounding box separately.
+ */
+export function renderTabStrip(width, tabs, activeTab) {
+    const sep = '   ';
+    const rendered = tabs.map((label, idx) => {
+        if (idx === activeTab) {
+            // Active: inverse-highlight with thin side-bars to evoke a
+            // selected pill. The ▎ left-eighth-block is visually subtle but
+            // unmistakable on every terminal that supports box-drawing.
+            return inverse(` ${label} `);
+        }
+        return ` ${label} `;
+    });
+    const inner = rendered.join(sep);
+    const padded = pad(inner, width, 'left');
+    return padded;
+}
+/**
+ * Render a vertical scroll indicator on the right edge of a panel.
+ * Shows "n / total" + a position blob if there's overflow.
+ *
+ *   ─ 24 / 412
+ */
+export function renderScrollIndicator(visible, total, selectedIdx) {
+    if (total <= visible)
+        return '';
+    return ` ${selectedIdx + 1} / ${total} `;
+}
+/**
+ * Word-wrap or hard-break `text` to lines of at most `width` visible
+ * chars. ANSI sequences are preserved across line boundaries; visible
+ * width is what's counted.
+ *
+ * Used for free-form prose in the Status / About panels.
+ */
+export function wrap(text, width) {
+    if (width <= 0)
+        return [];
+    const out = [];
+    for (const para of text.split('\n')) {
+        if (para === '') {
+            out.push('');
+            continue;
+        }
+        let line = '';
+        let lineWidth = 0;
+        for (const word of para.split(' ')) {
+            const w = visibleWidth(word);
+            // Word itself longer than width → hard-break it into chunks
+            // of `width` chars. Push the current accumulated line first so
+            // we don't lose pre-existing content.
+            if (w > width) {
+                if (lineWidth > 0) {
+                    out.push(line);
+                    line = '';
+                    lineWidth = 0;
+                }
+                let remaining = word;
+                while (visibleWidth(remaining) > width) {
+                    out.push(remaining.slice(0, width));
+                    remaining = remaining.slice(width);
+                }
+                line = remaining;
+                lineWidth = visibleWidth(remaining);
+                continue;
+            }
+            // Normal-width word: fit on current line if there's room, else
+            // wrap to a new line.
+            if (lineWidth === 0) {
+                line = word;
+                lineWidth = w;
+                continue;
+            }
+            if (lineWidth + 1 + w <= width) {
+                line += ' ' + word;
+                lineWidth += 1 + w;
+            }
+            else {
+                out.push(line);
+                line = word;
+                lineWidth = w;
+            }
+        }
+        if (line.length > 0)
+            out.push(line);
+    }
+    return out;
+}
+/**
+ * Render a left-key / right-value row (the shape every config/status
+ * line uses).
+ *
+ *   Port:               3456
+ *   Mode:               passthrough
+ *
+ * Key is left-padded to `keyWidth` so a column of rows aligns. Value
+ * is truncated to fit the remaining space.
+ */
+export function renderKvRow(key, value, totalWidth, keyWidth = 22) {
+    // Clamp keyWidth so a narrow terminal (totalWidth < keyWidth default)
+    // still produces a well-formed totalWidth-char row. The key gets
+    // truncated proportionally; the value column gets the rest.
+    const effectiveKeyWidth = Math.min(keyWidth, Math.max(1, totalWidth - 1));
+    const keyPart = pad(key + ':', effectiveKeyWidth);
+    // Value pad-to-width (not just truncate) so a full row reaches the
+    // panel edge — keeps backgrounds + borders aligned.
+    const valuePart = pad(value, totalWidth - effectiveKeyWidth);
+    return keyPart + valuePart;
+}