@north-light/crouter 0.3.154

package/dist/core/timing.js

@@ -0,0 +1,94 @@
+// timing.ts — CRTR_TIMING=1 cross-process phase markers for front-door latency.
+//
+// Why this exists: `node --cpu-prof` cannot see the front door, because opening
+// a node spans THREE processes — the `crtr` front-door process, the
+// `crtr surface attach` viewer it spawns, and the detached broker. A profile of
+// any one of them shows a fraction of the wall clock the user feels.
+//
+// So: hrtime-grade phase markers on ONE shared timeline. The first crtr process
+// to mark stamps `CRTR_TIMING_T0` (epoch ms, sub-ms precision) into its own env,
+// which every child it spawns inherits, so all three processes report offsets
+// from the same origin and the log reads as a single ordered timeline.
+//
+// The broker already emits `broker.startup.*` events carrying `duration_ms`
+// from its own process start (broker.ts / broker-cli.ts). This does NOT replace
+// or duplicate that shape — `mark()` mirrors the broker's `duration_ms` sense in
+// its `up=` column (ms since THIS process started), and adds the cross-process
+// `+` column the broker events cannot have.
+//
+// Off by default and effectively free when off: one env read, one comparison.
+// Output goes to stderr only — never stdout, which is the CLI's data contract.
+const FLAG = 'CRTR_TIMING';
+const ORIGIN = 'CRTR_TIMING_T0';
+/** Wall-clock epoch ms with sub-ms precision, comparable across processes. */
+function nowMs() {
+    return performance.timeOrigin + performance.now();
+}
+const enabled = (() => {
+    const v = process.env[FLAG];
+    return v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
+})();
+// The shared origin. Inherited when a parent crtr process already stamped it;
+// otherwise this process is the origin and stamps its own env so the viewer and
+// broker it spawns (both spawned with `{...process.env}`) land on this timeline.
+const t0 = (() => {
+    if (!enabled)
+        return 0;
+    const inherited = Number(process.env[ORIGIN]);
+    if (Number.isFinite(inherited) && inherited > 0)
+        return inherited;
+    // This process is the origin — and its own start, not the moment timing.ts
+    // was evaluated, so module-graph load time is inside the first interval.
+    const own = performance.timeOrigin;
+    process.env[ORIGIN] = String(own);
+    return own;
+})();
+/** Short label for which of the three processes a marker came from. */
+const proc = (() => {
+    const explicit = process.env['CRTR_TIMING_PROC'];
+    if (explicit !== undefined && explicit !== '')
+        return explicit;
+    // The attach viewer runs through the same cli entry as every other command;
+    // label it distinctly so a three-process timeline is readable at a glance.
+    if (process.argv[2] === 'surface' && process.argv[3] === 'attach')
+        return 'viewer';
+    return 'cli';
+})();
+let prev = 0;
+/** True when CRTR_TIMING is set — guard expensive marker payloads with this. */
+export function timingEnabled() {
+    return enabled;
+}
+/** Label this process in the timing log (e.g. 'viewer', 'broker'). */
+export function timingProc(name) {
+    if (!enabled)
+        return;
+    process.env['CRTR_TIMING_PROC'] = name;
+}
+/**
+ * Record one phase marker. Columns:
+ *   `+`  ms since the shared cross-process origin (the whole front-door clock)
+ *   `Δ`  ms since the previous marker in THIS process
+ *   `up` ms since this process started (same sense as broker `duration_ms`)
+ */
+export function mark(phase, fields) {
+    if (!enabled)
+        return;
+    const abs = nowMs();
+    const since = abs - t0;
+    const delta = prev === 0 ? since : abs - prev;
+    prev = abs;
+    const up = performance.now();
+    const tail = fields === undefined
+        ? ''
+        : ' ' +
+            Object.entries(fields)
+                .map(([k, v]) => `${k}=${String(v)}`)
+                .join(' ');
+    const name = process.env['CRTR_TIMING_PROC'] ?? proc;
+    const fmt = (n) => n.toFixed(1).padStart(8);
+    // `t=` is absolute epoch ms: the broker is spawned by crtrd, not by the
+    // front-door process, so it inherits no shared origin — the absolute stamp is
+    // what lets its markers be merged into the cli/viewer timeline after the fact.
+    process.stderr.write(`[timing] +${fmt(since)}ms Δ${fmt(delta)}ms up=${fmt(up)}ms t=${abs.toFixed(1)} ${name}/${process.pid} ${phase}${tail}\n`);
+}

package/dist/core/tui/__tests__/host-keybindings.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/tui/__tests__/host-keybindings.test.js

@@ -0,0 +1,113 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { resolveKeybindings } from '../../keybindings/index.js';
+import { matchViewBinding, matchesViewHostBinding, parseViewKeypress, resolveViewKeyHints } from '../host.js';
+function key(input = '', patch = {}) {
+    return {
+        upArrow: false,
+        downArrow: false,
+        leftArrow: false,
+        rightArrow: false,
+        return: false,
+        escape: false,
+        ctrl: false,
+        meta: false,
+        tab: false,
+        shiftTab: false,
+        backspace: false,
+        ...patch,
+    };
+}
+test('catalog view bindings use defaults, remaps, and effective hint labels', () => {
+    const keymap = [
+        { bindingId: 'crtr.view.canvas.down', intent: 'down', hint: { label: 'move' } },
+    ];
+    const defaults = resolveKeybindings();
+    assert.deepEqual(matchViewBinding(keymap, defaults, 'j', key('j'), { row: 0 }), { intent: 'down', payload: undefined });
+    // Bare printable keys render as typed — `j`, not a `J` nobody can press.
+    assert.deepEqual(resolveViewKeyHints(keymap, defaults, { row: 0 }), [{ keys: 'j / Down', label: 'move' }]);
+    const remapped = resolveKeybindings({ 'crtr.view.canvas.down': ['x'] });
+    assert.equal(matchViewBinding(keymap, remapped, 'j', key('j'), { row: 0 }), null);
+    assert.deepEqual(matchViewBinding(keymap, remapped, 'x', key('x'), { row: 0 }), { intent: 'down', payload: undefined });
+    assert.deepEqual(resolveViewKeyHints(keymap, remapped, { row: 0 }), [{ keys: 'x', label: 'move' }]);
+});
+test('custom view literals retain their matching and presenter-authored hints', () => {
+    const keymap = [
+        { keys: ['z'], intent: 'custom', hint: { keys: 'z', label: 'custom' } },
+    ];
+    const bindings = resolveKeybindings();
+    assert.deepEqual(matchViewBinding(keymap, bindings, 'z', key('z'), undefined), { intent: 'custom', payload: undefined });
+    assert.equal(matchViewBinding(keymap, bindings, 'x', key('x'), undefined), null);
+    assert.deepEqual(resolveViewKeyHints(keymap, bindings, undefined), [{ keys: 'z', label: 'custom' }]);
+});
+test('Alt+<letter> does not falsely match a bare custom literal', () => {
+    const keymap = [{ keys: ['q'], intent: 'quit' }];
+    const bindings = resolveKeybindings();
+    const altQ = parseViewKeypress(Buffer.from('\x1bq'));
+    assert.equal(matchViewBinding(keymap, bindings, altQ.input, altQ.key, undefined, altQ.raw), null);
+    const q = parseViewKeypress(Buffer.from('q'));
+    assert.deepEqual(matchViewBinding(keymap, bindings, q.input, q.key, undefined, q.raw), { intent: 'quit', payload: undefined });
+});
+test('host force quit and capture deletion follow catalog IDs through raw terminal decoding', () => {
+    const defaults = resolveKeybindings();
+    const ctrlC = parseViewKeypress(Buffer.from('\x03'));
+    const del = parseViewKeypress(Buffer.from('\x7f'), defaults);
+    const bs = parseViewKeypress(Buffer.from('\b'), defaults);
+    assert.ok(matchesViewHostBinding(defaults, 'crtr.view.host.force-quit', ctrlC.raw));
+    assert.ok(matchesViewHostBinding(defaults, 'crtr.view.host.editor.backspace', del.raw));
+    // 0x08 stays Backspace under default config so ^H-erase terminals still delete.
+    assert.ok(matchesViewHostBinding(defaults, 'crtr.view.host.editor.backspace', bs.raw));
+    const remapped = resolveKeybindings({
+        'crtr.view.host.force-quit': ['alt+x'],
+        'crtr.view.host.editor.backspace': ['ctrl+h'],
+    });
+    const altX = parseViewKeypress(Buffer.from('\x1bx'), remapped);
+    const ctrlH = parseViewKeypress(Buffer.from('\b'), remapped);
+    const delRemap = parseViewKeypress(Buffer.from('\x7f'), remapped);
+    assert.equal(matchesViewHostBinding(remapped, 'crtr.view.host.force-quit', ctrlC.raw), false);
+    assert.ok(matchesViewHostBinding(remapped, 'crtr.view.host.force-quit', altX.raw));
+    // With deletion remapped to Ctrl-H, the 0x08 byte deletes and DEL no longer does.
+    assert.equal(matchesViewHostBinding(remapped, 'crtr.view.host.editor.backspace', delRemap.raw), false);
+    assert.ok(matchesViewHostBinding(remapped, 'crtr.view.host.editor.backspace', ctrlH.raw));
+});
+test('Alt+Backspace deletes like Backspace under default config', () => {
+    const defaults = resolveKeybindings();
+    const altDel = parseViewKeypress(Buffer.from('\x1b\x7f'), defaults);
+    const altBs = parseViewKeypress(Buffer.from('\x1b\b'), defaults);
+    assert.ok(matchesViewHostBinding(defaults, 'crtr.view.host.editor.backspace', altDel.raw));
+    assert.ok(matchesViewHostBinding(defaults, 'crtr.view.host.editor.backspace', altBs.raw));
+});
+test('raw terminal decoding covers modified arrows and enter/return equivalence', () => {
+    const keymap = [{ bindingId: 'crtr.view.chat.submit', intent: 'submit' }];
+    const bindings = resolveKeybindings();
+    const cr = parseViewKeypress(Buffer.from('\r'));
+    const lf = parseViewKeypress(Buffer.from('\n'));
+    assert.deepEqual(matchViewBinding(keymap, bindings, cr.input, cr.key, undefined, cr.raw), { intent: 'submit', payload: undefined });
+    assert.deepEqual(matchViewBinding(keymap, bindings, lf.input, lf.key, undefined, lf.raw), { intent: 'submit', payload: undefined });
+    const ctrlUp = parseViewKeypress(Buffer.from('\x1b[1;5A'));
+    assert.equal(ctrlUp.raw.upArrow, true);
+    assert.equal(ctrlUp.raw.ctrl, true);
+    const up = parseViewKeypress(Buffer.from('\x1b[A'));
+    assert.equal(up.raw.upArrow, true);
+    assert.equal(up.raw.ctrl, false);
+});
+test('a disabled binding neither matches nor renders a hint', () => {
+    const keymap = [
+        { bindingId: 'crtr.view.canvas.refresh', intent: 'refresh', hint: { label: 'refresh' } },
+    ];
+    const bindings = resolveKeybindings({ 'crtr.view.canvas.refresh': [] });
+    const g = parseViewKeypress(Buffer.from('g'));
+    assert.equal(matchViewBinding(keymap, bindings, g.input, g.key, undefined, g.raw), null);
+    assert.deepEqual(resolveViewKeyHints(keymap, bindings, undefined), []);
+});
+test('capture hints are host-owned, mode-gated, and keep custom KeyHint keys verbatim', () => {
+    const gated = [
+        { capture: 'setDraft', when: (state) => state.compose, hint: { label: 'compose' } },
+    ];
+    assert.deepEqual(resolveViewKeyHints(gated, resolveKeybindings(), { compose: true }), [{ keys: 'type', label: 'compose' }]);
+    assert.deepEqual(resolveViewKeyHints(gated, resolveKeybindings(), { compose: false }), []);
+    const custom = [
+        { capture: 'setDraft', when: () => true, hint: { keys: 'edit', label: 'compose' } },
+    ];
+    assert.deepEqual(resolveViewKeyHints(custom, resolveKeybindings(), undefined), [{ keys: 'edit', label: 'compose' }]);
+});

package/dist/core/tui/draw.d.ts

@@ -0,0 +1,100 @@
+export interface Size {
+    cols: number;
+    rows: number;
+}
+export interface Rect {
+    row: number;
+    col: number;
+    width: number;
+    height: number;
+}
+export interface Style {
+    fg?: string;
+    bg?: string;
+    bold?: boolean;
+    dim?: boolean;
+    reverse?: boolean;
+}
+export interface Span {
+    text: string;
+    style?: Style;
+}
+/** An SGR fg/bg parameter is digits and semicolons only (e.g. '32', '1;36', '236').
+ *  Guards styleSpan against a non-numeric value (a color name) producing a broken
+ *  escape sequence. */
+export declare function isSgrParams(v: string): boolean;
+/** Style one chunk of text. Hue (fg/bg) is gated on `color`; bold/dim/reverse
+ *  are not. After the styled text we return to `lineBase` (not a bare reset) so a
+ *  row-level background/dim persists across spans instead of bleeding or being
+ *  cleared. */
+export declare function styleSpan(text: string, style: Style | undefined, color: boolean, lineBase: string): string;
+/** Assemble styled spans into one line clipped to `width` visible cols. When
+ *  `fill`, pad the remainder with spaces (under `lineBase`) so a cursor-row
+ *  background spans the full width. Always RESET-terminated so no color bleeds
+ *  into the next line. */
+export declare function assemble(spans: Span[], width: number, color: boolean, lineBase: string, fill: boolean): string;
+/** Truncate to `max` visible cols (plain text, no ANSI). */
+export declare function clip(text: string, max: number): string;
+export interface ColorCaps {
+    /** Any hue (fg/bg color) allowed. */
+    color: boolean;
+    /** 256-color bg allowed — drives the subtle cursor-row background. */
+    color256: boolean;
+}
+/** Detect color capability. Honors `NO_COLOR` and `TERM=dumb`, and only emits
+ *  hue when stdout is a TTY. `color256` additionally requires a 256/truecolor
+ *  terminal (for the cursor-row background; otherwise we fall back to reverse). */
+export declare function detectColorCaps(stream?: {
+    isTTY?: boolean;
+}, env?: NodeJS.ProcessEnv): ColorCaps;
+/** One pre-styled list row (the view styles its own spans; `list` windows + the
+ *  cursor highlight are the host's job). An optional `right` group is flush-right
+ *  on the row (e.g. a timestamp) via spansRight; the left `spans` are clipped to
+ *  leave room for it, and the cursor-row highlight merges over both. */
+export interface ListItemRow {
+    spans: Span[];
+    right?: Span[];
+    /** Optional continuation lines drawn under `spans` as part of the SAME item
+     *  (e.g. a wrapped subtitle). They share the item's cursor highlight and the
+     *  item still counts as one cursor position; the list windows by screen rows. */
+    lines?: Span[][];
+}
+/** Adjusted scroll the view stores back so the cursor stays visible. */
+export interface ListResult {
+    scroll: number;
+}
+export interface Draw {
+    readonly size: Size;
+    readonly caps: ColorCaps;
+    /** Styled spans at an absolute cell, clipped to maxWidth (default → edge). */
+    spans(row: number, col: number, spans: Span[], maxWidth?: number): void;
+    /** Flush-right span placement (mirror of `spans`): the group's last visible
+     *  cell lands just before `rightCol` (i.e. start col = rightCol − visibleWidth,
+     *  rightCol exclusive). If the group exceeds `maxWidth` (default → the room left
+     *  of rightCol) the LEFT end is clipped with a leading `…`. */
+    spansRight(row: number, rightCol: number, spans: Span[], maxWidth?: number): void;
+    /** Convenience single span. */
+    text(row: number, col: number, text: string, style?: Style): void;
+    /** Dim horizontal rule across [fromCol,toCol) (default full width). */
+    hline(row: number, fromCol?: number, toCol?: number, ch?: string): void;
+    /** Dim vertical rule down column `col` across [fromRow,toRow) (default full
+     *  height). `ch` defaults to `│`; pass `|` as the ASCII fallback. */
+    vline(col: number, fromRow?: number, toRow?: number, ch?: string): void;
+    /** Single-line box border around rect (optional title in the top edge). */
+    box(rect: Rect, title?: string): void;
+    /** Split a rect into N columns by weights. */
+    columns(rect: Rect, weights: number[]): Rect[];
+    /** Scrollable list within rect: windows `items` to fit height, highlights the
+     *  cursor row (256-bg or reverse fallback, like browse). Returns adjusted
+     *  scroll so the cursor stays visible — the view stores it in state. */
+    list(rect: Rect, items: ListItemRow[], cursor: number, scroll: number): ListResult;
+}
+/** A live Draw plus the host-side serializer. */
+export interface DrawHandle {
+    draw: Draw;
+    /** Serialize the buffer to a full repaint frame (home + per-line clear + clear
+     *  below) — identical framing to browse's renderFrame. */
+    frame(): string;
+}
+/** Create a screen-sized cell buffer + the absolute-cell Draw API over it. */
+export declare function createDraw(size: Size, caps: ColorCaps): DrawHandle;

package/dist/core/tui/draw.js

@@ -0,0 +1,359 @@
+// draw.ts — the generic immediate-mode drawing surface shared by every crtr
+// raw-ANSI TUI (the `crtr view` host and `canvas browse`).
+//
+// The span/color primitives (Span, styleSpan, assemble, clip, ColorCaps,
+// detectColorCaps) are extracted verbatim-in-behavior from
+// canvas/browse/render.ts so there is ONE copy; browse imports them back.
+//
+// On top of those primitives this module adds the `Draw` factory: a line/cell
+// buffer covering the screen that a view fills via absolute-cell helpers
+// (spans/text/hline/box/columns/list). The host allocates one Draw per frame,
+// draws its chrome into it, hands the view a content Rect, then serializes the
+// buffer to a single repaint frame (`\x1b[H` + per-line `\x1b[K` + `\x1b[J`) —
+// exactly like browse's renderFrame does today.
+//
+// COLOR: hue (fg/bg) is gated on `caps.color`; structural SGR (bold/dim/reverse)
+// is always allowed. 256-color bg (the cursor-row highlight) additionally needs
+// `caps.color256`, falling back to reverse.
+// ── ANSI ────────────────────────────────────────────────────────────────────
+const ESC = '\x1b[';
+const RESET = `${ESC}0m`;
+const REVERSE = `${ESC}7m`;
+const DIM = `${ESC}2m`;
+const BOLD = `${ESC}1m`;
+/** An SGR fg/bg parameter is digits and semicolons only (e.g. '32', '1;36', '236').
+ *  Guards styleSpan against a non-numeric value (a color name) producing a broken
+ *  escape sequence. */
+export function isSgrParams(v) {
+    return v.length > 0 && /^[0-9;]+$/.test(v);
+}
+/** Style one chunk of text. Hue (fg/bg) is gated on `color`; bold/dim/reverse
+ *  are not. After the styled text we return to `lineBase` (not a bare reset) so a
+ *  row-level background/dim persists across spans instead of bleeding or being
+ *  cleared. */
+export function styleSpan(text, style, color, lineBase) {
+    if (text === '')
+        return '';
+    let pre = '';
+    if (style?.dim)
+        pre += DIM;
+    if (style?.bold)
+        pre += BOLD;
+    if (style?.reverse)
+        pre += REVERSE;
+    // fg is an SGR parameter string (e.g. '32' or '1;36'); bg is a 256-color index.
+    // Reject anything else so a bad value (e.g. a color NAME like 'green') degrades
+    // to no-color instead of emitting an invalid CSI that prints as literal garbage.
+    if (color && style?.fg && isSgrParams(style.fg))
+        pre += `${ESC}${style.fg}m`;
+    if (color && style?.bg && isSgrParams(style.bg))
+        pre += `${ESC}48;5;${style.bg}m`;
+    if (pre === '')
+        return text; // inherits lineBase / default
+    return `${pre}${text}${RESET}${lineBase}`;
+}
+/** Assemble styled spans into one line clipped to `width` visible cols. When
+ *  `fill`, pad the remainder with spaces (under `lineBase`) so a cursor-row
+ *  background spans the full width. Always RESET-terminated so no color bleeds
+ *  into the next line. */
+export function assemble(spans, width, color, lineBase, fill) {
+    let used = 0;
+    let body = '';
+    for (const span of spans) {
+        if (used >= width)
+            break;
+        if (span.text === '')
+            continue;
+        let t = span.text;
+        const remaining = width - used;
+        let cut = false;
+        if (t.length > remaining) {
+            t = t.slice(0, Math.max(0, remaining - 1)) + '…';
+            cut = true;
+        }
+        body += styleSpan(t, span.style, color, lineBase);
+        used += t.length;
+        if (cut)
+            break;
+    }
+    if (fill && used < width)
+        body += ' '.repeat(width - used);
+    return lineBase === '' ? body : `${lineBase}${body}${RESET}`;
+}
+/** Truncate to `max` visible cols (plain text, no ANSI). */
+export function clip(text, max) {
+    if (max <= 0)
+        return '';
+    return text.length <= max ? text : text.slice(0, Math.max(0, max - 1)) + '…';
+}
+/** Detect color capability. Honors `NO_COLOR` and `TERM=dumb`, and only emits
+ *  hue when stdout is a TTY. `color256` additionally requires a 256/truecolor
+ *  terminal (for the cursor-row background; otherwise we fall back to reverse). */
+export function detectColorCaps(stream = process.stdout, env = process.env) {
+    const term = env['TERM'] ?? '';
+    const color = stream.isTTY === true && !env['NO_COLOR'] && term !== 'dumb';
+    const colorTerm = env['COLORTERM'] ?? '';
+    const color256 = color && (/256|direct/i.test(term) || /truecolor|24bit/i.test(colorTerm));
+    return { color, color256 };
+}
+function mergeStyle(base, top) {
+    if (!top)
+        return base;
+    return {
+        fg: top.fg ?? base.fg,
+        bg: top.bg ?? base.bg,
+        bold: top.bold || base.bold,
+        dim: top.dim || base.dim,
+        reverse: top.reverse || base.reverse,
+    };
+}
+function sameStyle(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    return a.fg === b.fg && a.bg === b.bg
+        && !!a.bold === !!b.bold && !!a.dim === !!b.dim && !!a.reverse === !!b.reverse;
+}
+/** Create a screen-sized cell buffer + the absolute-cell Draw API over it. */
+export function createDraw(size, caps) {
+    const cols = Math.max(1, size.cols);
+    const rows = Math.max(1, size.rows);
+    const grid = [];
+    for (let r = 0; r < rows; r++) {
+        const line = new Array(cols);
+        for (let c = 0; c < cols; c++)
+            line[c] = { ch: ' ', style: undefined };
+        grid.push(line);
+    }
+    /** Place spans starting at (row, col), clipped to `limit` visible cells; each
+     *  span's style optionally merged under `base` (the cursor-row highlight). */
+    const place = (row, col, spans, maxWidth, base) => {
+        if (row < 0 || row >= rows)
+            return;
+        const edge = cols - col;
+        const limit = Math.min(maxWidth ?? edge, edge);
+        if (limit <= 0)
+            return;
+        let x = col;
+        let drawn = 0;
+        for (const span of spans) {
+            if (drawn >= limit)
+                break;
+            const style = base ? mergeStyle(base, span.style) : span.style;
+            for (const ch of Array.from(span.text)) {
+                if (drawn >= limit)
+                    break;
+                if (x >= 0 && x < cols)
+                    grid[row][x] = { ch, style };
+                x++;
+                drawn++;
+            }
+        }
+    };
+    const fillStyle = (row, col, width, style) => {
+        if (row < 0 || row >= rows)
+            return;
+        const end = Math.min(cols, col + width);
+        for (let x = Math.max(0, col); x < end; x++)
+            grid[row][x] = { ch: ' ', style };
+    };
+    /** Visible (column) width of a span group — ANSI-free cell count. */
+    const spanWidth = (spans) => {
+        let n = 0;
+        for (const s of spans)
+            n += Array.from(s.text).length;
+        return n;
+    };
+    /** Flatten spans to per-cell {ch,style}, then re-group consecutive same-style
+     *  cells back into spans — used to left-clip a flush-right group. */
+    const regroup = (cells) => {
+        const out = [];
+        for (const c of cells) {
+            const last = out[out.length - 1];
+            if (last && sameStyle(last.style, c.style))
+                last.text += c.ch;
+            else
+                out.push({ text: c.ch, style: c.style });
+        }
+        return out;
+    };
+    /** Flush-right placement shared by draw.spansRight and the list right-group.
+     *  Lays `spans` so the group ends just before `rightCol` (exclusive); clips the
+     *  LEFT end with a leading `…` when the group exceeds the effective width.
+     *  `base` (the cursor-row highlight) merges under each cell, like `place`. */
+    const placeRight = (row, rightCol, spans, maxWidth, base) => {
+        if (row < 0 || row >= rows)
+            return;
+        const cap = Math.max(0, rightCol); // room available left of rightCol
+        const max = Math.min(maxWidth ?? cap, cap);
+        if (max <= 0)
+            return;
+        let cells = [];
+        for (const s of spans)
+            for (const ch of Array.from(s.text))
+                cells.push({ ch, style: s.style });
+        if (cells.length === 0)
+            return;
+        if (cells.length > max) {
+            const drop = cells.length - max + 1; // make room for the leading …
+            cells = cells.slice(drop);
+            cells.unshift({ ch: '…', style: cells[0]?.style });
+        }
+        const startCol = rightCol - cells.length;
+        place(row, startCol, regroup(cells), undefined, base);
+    };
+    const draw = {
+        size: { cols, rows },
+        caps,
+        spans(row, col, spans, maxWidth) {
+            place(row, col, spans, maxWidth);
+        },
+        spansRight(row, rightCol, spans, maxWidth) {
+            placeRight(row, rightCol, spans, maxWidth);
+        },
+        text(row, col, text, style) {
+            place(row, col, [{ text, style }], undefined);
+        },
+        hline(row, fromCol = 0, toCol = cols, ch = '─') {
+            if (row < 0 || row >= rows)
+                return;
+            const a = Math.max(0, Math.min(cols, fromCol));
+            const b = Math.max(0, Math.min(cols, toCol));
+            for (let x = a; x < b; x++)
+                grid[row][x] = { ch, style: { dim: true } };
+        },
+        vline(col, fromRow = 0, toRow = rows, ch = '│') {
+            if (col < 0 || col >= cols)
+                return;
+            const a = Math.max(0, Math.min(rows, fromRow));
+            const b = Math.max(0, Math.min(rows, toRow));
+            for (let r = a; r < b; r++)
+                grid[r][col] = { ch, style: { dim: true } };
+        },
+        box(rect, title) {
+            const { row, col, width, height } = rect;
+            if (width < 2 || height < 2)
+                return;
+            const bs = { dim: true };
+            const right = col + width - 1;
+            const bottom = row + height - 1;
+            const horiz = '─'.repeat(Math.max(0, width - 2));
+            place(row, col, [{ text: `┌${horiz}┐`, style: bs }], width);
+            place(bottom, col, [{ text: `└${horiz}┘`, style: bs }], width);
+            for (let r = row + 1; r < bottom; r++) {
+                place(r, col, [{ text: '│', style: bs }], 1);
+                place(r, right, [{ text: '│', style: bs }], 1);
+            }
+            if (title !== undefined && title !== '' && width > 4) {
+                place(row, col + 2, [{ text: ` ${title} ` }], width - 4);
+            }
+        },
+        columns(rect, weights) {
+            const n = weights.length;
+            if (n === 0)
+                return [];
+            const total = weights.reduce((a, b) => a + (b > 0 ? b : 0), 0) || 1;
+            const out = [];
+            let x = rect.col;
+            let used = 0;
+            for (let i = 0; i < n; i++) {
+                const isLast = i === n - 1;
+                const w = isLast
+                    ? Math.max(0, rect.width - used)
+                    : Math.max(0, Math.floor((rect.width * Math.max(0, weights[i])) / total));
+                out.push({ row: rect.row, col: x, width: w, height: rect.height });
+                x += w;
+                used += w;
+            }
+            return out;
+        },
+        list(rect, items, cursor, scroll) {
+            const height = Math.max(0, rect.height);
+            // An item may span several screen rows (its head plus any continuation
+            // lines), so scroll stays an ITEM index while windowing counts rows.
+            const rowsOf = (i) => 1 + (items[i]?.lines?.length ?? 0);
+            let sc = scroll;
+            if (sc < 0)
+                sc = 0;
+            if (sc > Math.max(0, items.length - 1))
+                sc = Math.max(0, items.length - 1);
+            if (height > 0) {
+                if (cursor < sc)
+                    sc = cursor;
+                // Scroll down until the cursor item's rows fit in the window (or it is
+                // the first item shown, in which case it is clipped rather than lost).
+                for (;;) {
+                    let used = 0;
+                    for (let i = sc; i <= cursor && i < items.length; i++)
+                        used += rowsOf(i);
+                    if (used <= height || sc >= cursor)
+                        break;
+                    sc++;
+                }
+            }
+            let rowIdx = rect.row;
+            const limit = rect.row + height;
+            for (let i = sc; i < items.length && rowIdx < limit; i++) {
+                const item = items[i];
+                const base = i === cursor
+                    ? (caps.color256 ? { bg: '236' } : { reverse: true })
+                    : undefined;
+                if (base)
+                    fillStyle(rowIdx, rect.col, rect.width, base);
+                if (item.right && item.right.length) {
+                    // Right-flush group (e.g. a timestamp); clip the left spans so they
+                    // never collide, and merge the cursor highlight over both.
+                    const rightWidth = spanWidth(item.right);
+                    const leftLimit = Math.max(0, rect.width - rightWidth - 1);
+                    place(rowIdx, rect.col, item.spans, leftLimit, base);
+                    placeRight(rowIdx, rect.col + rect.width, item.right, rightWidth, base);
+                }
+                else {
+                    place(rowIdx, rect.col, item.spans, rect.width, base);
+                }
+                rowIdx++;
+                for (const cont of item.lines ?? []) {
+                    if (rowIdx >= limit)
+                        break;
+                    if (base)
+                        fillStyle(rowIdx, rect.col, rect.width, base);
+                    place(rowIdx, rect.col, cont, rect.width, base);
+                    rowIdx++;
+                }
+            }
+            return { scroll: sc };
+        },
+    };
+    const serializeRow = (cells) => {
+        // Trim trailing plain blanks (clear-to-EOL covers them); keep styled tails
+        // (e.g. a cursor-row background fill) intact.
+        let last = -1;
+        for (let i = cells.length - 1; i >= 0; i--) {
+            const c = cells[i];
+            if (c.ch !== ' ' || c.style !== undefined) {
+                last = i;
+                break;
+            }
+        }
+        if (last < 0)
+            return '';
+        let out = '';
+        let i = 0;
+        while (i <= last) {
+            const style = cells[i].style;
+            let text = '';
+            while (i <= last && sameStyle(cells[i].style, style)) {
+                text += cells[i].ch;
+                i++;
+            }
+            out += styleSpan(text, style, caps.color, '');
+        }
+        return out;
+    };
+    const frame = () => {
+        const body = grid.map((cells) => `${serializeRow(cells)}${ESC}K`).join('\r\n');
+        return `${ESC}H${body}${ESC}J`;
+    };
+    return { draw, frame };
+}