tui-cap 0.1.0

package/dist/parse.js

@@ -0,0 +1,659 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAnsiToGrid = parseAnsiToGrid;
+exports.extractFrames = extractFrames;
+exports.chooseFrame = chooseFrame;
+exports.trimBackgroundBleed = trimBackgroundBleed;
+exports.framePreview = framePreview;
+const headless_1 = require("@xterm/headless");
+const palette_1 = require("./palette");
+const timing_1 = require("./timing");
+const animation_1 = require("./animation");
+// Alternate-screen enter (DECSET 1049, also 47/1047). A stream that switches to
+// the alternate buffer is a full-screen TUI: it owns the whole window and
+// repaints in place, so only the final frame is meaningful.
+const ALT_SCREEN_ENTER = /\x1b\[\?(?:1049|1047|47)h/;
+function resolveMode(requested, text) {
+    if (requested !== 'auto')
+        return requested;
+    return ALT_SCREEN_ENTER.test(text) ? 'final-frame' : 'full-scroll';
+}
+function rowHasContent(cells) {
+    return cells.some((c) => c.char.trim() !== '' || c.bg !== null);
+}
+/**
+ * Replay a raw ANSI/VT byte stream through a headless terminal emulator and
+ * read back a single on-screen grid as styled cells.
+ *
+ * `final-frame` returns the visible window at the end of the stream;
+ * `full-scroll` returns the whole buffer (viewport + scrollback). For
+ * multi-frame extraction of a full-screen TUI (every paint cycle), use
+ * {@link extractFrames} instead.
+ */
+async function parseAnsiToGrid(data, opts) {
+    const text = typeof data === 'string' ? data : data.toString('utf8');
+    const theme = opts.theme ?? 'dark';
+    const warn = opts.warn ?? ((m) => console.error(m));
+    const mode = resolveMode(opts.mode ?? 'auto', text);
+    const fullScroll = mode === 'full-scroll';
+    const maxRows = Math.max(1, Math.floor(opts.maxRows ?? 1000));
+    // full-scroll keeps up to `maxRows` total lines (viewport + scrollback); the
+    // emulator caps total buffer height at `scrollback + rows`, so size the
+    // scrollback so the buffer holds at most `maxRows` lines.
+    const scrollback = fullScroll ? Math.max(0, maxRows - opts.rows) : 0;
+    const term = new headless_1.Terminal({
+        cols: opts.cols,
+        rows: opts.rows,
+        allowProposedApi: true,
+        scrollback,
+    });
+    // Count lines that scroll off the top so we can detect (and report) loss.
+    // In final-frame each scrolled line is gone for good; in full-scroll a line is
+    // only lost once it scrolls past the (sized) scrollback.
+    let scrolledLines = 0;
+    const disposeScroll = term.onScroll(() => {
+        scrolledLines += 1;
+    });
+    await new Promise((resolve) => term.write(text, () => resolve()));
+    // buffer.active is whichever buffer is in use at the end of the stream — the
+    // alternate buffer for a full-screen TUI, the normal buffer otherwise.
+    const buffer = term.buffer.active;
+    let readStart;
+    let readEnd;
+    if (fullScroll) {
+        // Read the whole buffer (scrollback + viewport); the emulator already
+        // dropped anything older than the cap.
+        readStart = 0;
+        readEnd = buffer.length;
+        const total = scrolledLines + opts.rows;
+        if (scrolledLines > scrollback) {
+            // More scrolled than the scrollback could hold → oldest rows truncated.
+            warn(`Warning: captured ~${total} rows but --max-rows is ${maxRows}; kept the ` +
+                `most recent ${maxRows} (oldest ~${total - maxRows} truncated). ` +
+                `Increase --max-rows to capture everything.`);
+        }
+    }
+    else {
+        // final-frame: just the visible window.
+        readStart = 0;
+        readEnd = opts.rows;
+        // Don't silently drop content (v0.1 bug F1). If we're on the normal buffer
+        // and lines scrolled past the top, they were truncated — warn so it's never
+        // quiet. The alternate buffer (full-screen TUI) intentionally shows only the
+        // final frame, so suppress the warning there.
+        if (scrolledLines > 0 && buffer.type !== 'alternate') {
+            warn(`Warning: ${scrolledLines} line(s) scrolled past the top of the ` +
+                `${opts.rows}-row capture window and were not captured. Use ` +
+                `--mode full-scroll (or increase --rows) to capture everything.`);
+        }
+    }
+    disposeScroll.dispose();
+    const lines = [];
+    for (let y = readStart; y < readEnd; y++) {
+        lines.push(readLine(buffer.getLine(y), opts.cols, theme));
+    }
+    // full-scroll grids end at real content; trim trailing blank rows so the SVG
+    // (and the row count) reflect the captured output, not the empty tail of the
+    // viewport. final-frame keeps a fixed window.
+    if (fullScroll) {
+        while (lines.length > 1 && !rowHasContent(lines[lines.length - 1])) {
+            lines.pop();
+        }
+    }
+    term.dispose();
+    return { cols: opts.cols, rows: lines.length, lines };
+}
+// Matches the screen-replacing control sequences we cut frames on:
+//   ESC[?1049h / ?1047h / ?47h   enter alternate buffer   (group 1 = 'h')
+//   ESC[?1049l / ?1047l / ?47l   leave alternate buffer   (group 1 = 'l')
+//   ESC[?25h                     show cursor (paint done)  (group 2)
+//   ESC[?2026l                   end synchronized update   (group 3)
+//   ESC[<row;col>H               cursor position          (group 4 = params)
+//   ESC[<n>J                     erase in display          (group 5 = params)
+const SEQ = /\x1b\[(?:\?(?:1049|1047|47)([hl])|(\?25h)|(\?2026l)|([0-9;]*)H|([0-9;]*)J)/g;
+function isHome(params) {
+    const row = params.split(';')[0];
+    return row === '' || row === '1';
+}
+function findBoundaries(text) {
+    const out = [];
+    for (const m of text.matchAll(SEQ)) {
+        const start = m.index;
+        if (m[1]) {
+            out.push({ start, kind: m[1] === 'h' ? 'enter' : 'leave' });
+        }
+        else if (m[2]) {
+            // Cursor-show marks the end of a paint cycle: TUIs hide the cursor,
+            // repaint in place, then show it again. Snapshotting here recovers one
+            // frame per repaint, giving the timeline fine temporal detail. Identical
+            // consecutive frames are collapsed later, so static screens stay compact.
+            out.push({ start, kind: 'paint' });
+        }
+        else if (m[3]) {
+            // End of a synchronized update (DECRST 2026 — BSU `?2026h` … ESU `?2026l`).
+            // Ink-style TUIs (the Copilot CLI) wrap every atomic redraw in a sync block
+            // and keep the cursor *hidden* for the whole duration of an interaction —
+            // opening a menu, arrowing through it, and closing it all happen with the
+            // cursor down, so the `?25h` paint signal never fires while those screens
+            // are visible. Cutting a frame at each ESU recovers one snapshot per atomic
+            // update, which is what makes submenu navigation (e.g. /agents, /delegate)
+            // and in-tab list highlighting show up on the timeline at all. Identical
+            // consecutive frames are collapsed later, so static screens stay compact.
+            out.push({ start, kind: 'flush' });
+        }
+        else if (m[4] !== undefined) {
+            // Cursor-home (`ESC[H`, `ESC[1;1H`) marks an in-place repaint: the TUI
+            // homes the cursor and redraws. Snapshotting here recovers one frame per
+            // repaint, which is what makes tab switches and other full-redraws show up
+            // on the timeline. Always on — identical consecutive frames are collapsed
+            // later, so static screens stay compact.
+            if (isHome(m[4]))
+                out.push({ start, kind: 'repaint' });
+        }
+        else if (m[5] !== undefined) {
+            // Only full-screen erases reset a frame; partial erases (0J/1J) don't.
+            if (m[5] === '2' || m[5] === '3')
+                out.push({ start, kind: 'clear' });
+        }
+    }
+    return out;
+}
+function readGrid(term, cols, rows, theme) {
+    const buffer = term.buffer.active;
+    const lines = [];
+    for (let y = 0; y < rows; y++) {
+        lines.push(readLine(buffer.getLine(y), cols, theme));
+    }
+    return { cols, rows, lines };
+}
+function isBlank(grid) {
+    return grid.lines.every((line) => line.every((c) => c.char.trim() === ''));
+}
+function signature(grid) {
+    return grid.lines
+        .map((line) => line
+        .map((c) => {
+        // Style flags that change a cell's visible appearance. Folding them
+        // into the signature keeps highlight-only moves — a selected menu row
+        // that changes only its background fill or flips to reverse-video,
+        // with the same text and foreground — from collapsing into the
+        // previous frame, so list navigation actually shows up on the timeline.
+        const flags = (c.bold ? 'b' : '') +
+            (c.italic ? 'i' : '') +
+            (c.underline ? 'u' : '') +
+            (c.dim ? 'd' : '') +
+            (c.strike ? 's' : '') +
+            (c.inverse ? 'r' : '');
+        return `${c.col}:${c.char}:${c.fg ?? ''}:${c.bg ?? ''}:${flags}`;
+    })
+        .join(''))
+        .join('\n');
+}
+// The Copilot CLI prompt input box draws its content on a row that begins with
+// a heavy vertical bar (U+2503 "┃"), e.g. "┃ my prompt", and wraps that row (or
+// rows) in a heavy border whose left edge caps are "╻" (U+257B) just above the
+// top content row and "╹" (U+2579) just below the bottom one.
+//
+// Two things together identify a *genuine editable prompt* and reject the
+// look-alikes that also begin a row with "┃":
+//   1. The caps: a stray box right-border "┃" on an otherwise-blank row has no
+//      ╻/╹ around it, so it is skipped.
+//   2. Flush to column 0: the prompt input always spans the full terminal width
+//      with its border at column 0, whereas selected issue/PR list rows are
+//      drawn in the *same* heavy box but inset by one column (marker at col 1).
+//      Requiring the marker at column 0 keeps the caret off those menu items.
+const INPUT_MARKER = '\u2503';
+const INPUT_CAP_TOP = '\u257b'; // ╻ — left-edge cap above the prompt content
+const INPUT_CAP_BOTTOM = '\u2579'; // ╹ — left-edge cap below the prompt content
+/** The first non-blank cell of a grid row (its glyph + visual column), or null
+ *  when the row is blank. */
+function firstCell(line) {
+    for (const cell of line) {
+        if (cell.char.trim() !== '')
+            return { char: cell.char, col: cell.col };
+    }
+    return null;
+}
+/** Locate the prompt input box on a frame, or null if none is present. Only a
+ *  genuine editable prompt counts: the run of "┃" content rows must be wrapped
+ *  by the box's heavy left-edge caps (╻ above, ╹ below) *and* sit flush at
+ *  column 0. That rejects stray box right-borders (no caps) and selected
+ *  issue/PR list rows (drawn in the same box but inset one column). The last
+ *  matching row wins so a prompt wrapped onto multiple "┃" rows resolves to its
+ *  final line. */
+function findInputBox(grid) {
+    let found = null;
+    for (let r = 0; r < grid.lines.length; r++) {
+        const line = grid.lines[r];
+        let first = -1;
+        for (let c = 0; c < line.length; c++) {
+            if (line[c].char.trim() !== '') {
+                first = c;
+                break;
+            }
+        }
+        if (first < 0 || line[first].char !== INPUT_MARKER)
+            continue;
+        // A real prompt input sits flush at the left edge; selected issue/PR list
+        // rows use the same heavy box but are inset one column. Skip anything that
+        // isn't flush at column 0.
+        if (line[first].col !== 0)
+            continue;
+        // Walk the contiguous run of flush "┃"-led rows this row belongs to, then
+        // require the rows just outside it to be the prompt box's heavy caps, also
+        // flush at column 0. Without both caps this "┃" is a menu/border edge.
+        const isFlushMarkerRow = (l) => {
+            const fc = firstCell(l);
+            return fc !== null && fc.char === INPUT_MARKER && fc.col === 0;
+        };
+        let top = r;
+        while (top - 1 >= 0 && isFlushMarkerRow(grid.lines[top - 1]))
+            top--;
+        let bottom = r;
+        while (bottom + 1 < grid.lines.length && isFlushMarkerRow(grid.lines[bottom + 1])) {
+            bottom++;
+        }
+        const aboveCap = top - 1 >= 0 ? firstCell(grid.lines[top - 1]) : null;
+        const belowCap = bottom + 1 < grid.lines.length ? firstCell(grid.lines[bottom + 1]) : null;
+        const cappedAbove = aboveCap?.char === INPUT_CAP_TOP && aboveCap.col === 0;
+        const cappedBelow = belowCap?.char === INPUT_CAP_BOTTOM && belowCap.col === 0;
+        if (!cappedAbove || !cappedBelow)
+            continue;
+        let last = -1;
+        for (let c = line.length - 1; c >= 0; c--) {
+            if (line[c].char.trim() !== '') {
+                last = c;
+                break;
+            }
+        }
+        const markerCol = line[first].col;
+        const hasText = last > first;
+        // Where the caret rests. While composing a slash command the CLI appends an
+        // autocomplete *ghost* suggestion after the typed text, rendered in the
+        // theme's muted foreground (the typed text keeps the prompt's normal fg). In
+        // the real UI the caret stays at the end of what the user actually typed,
+        // overlapping the first ghost glyph — so peel back any trailing run whose
+        // foreground differs from the typed text and rest the caret at its start.
+        let caretCol;
+        if (!hasText) {
+            caretCol = markerCol + 2;
+        }
+        else {
+            const content = [];
+            for (let c = first + 1; c <= last; c++) {
+                if (line[c].char.trim() !== '')
+                    content.push(line[c]);
+            }
+            const typedFg = content[0].fg;
+            let k = content.length - 1;
+            while (k >= 1 && content[k].fg !== typedFg)
+                k--;
+            caretCol =
+                k === content.length - 1
+                    ? content[k].col + content[k].width // no ghost — rest just past the text
+                    : content[k + 1].col; // ghost present — rest over its first glyph
+        }
+        found = { row: r, caretCol, hasText };
+    }
+    return found;
+}
+/**
+ * Tag which frames are user typing, how many characters landed on each, and
+ * where the prompt caret sits.
+ *
+ * With keystroke data (`input`, on the same clock as the frame start times) each
+ * burst is attributed to the first frame that appeared at or after it — the
+ * paint that echoed those characters — so that frame's `typedChars` grows and
+ * `isTyping` is set. Without keystroke data, and when `detectFromContent` is on,
+ * typing is inferred from the input box gaining characters frame-to-frame.
+ *
+ * The typing `caret` is independent of the typing flags: it marks where the
+ * prompt cursor sits, and is placed on **every** frame that has an input box —
+ * tracking the end of any typed text, or resting at the start of an empty
+ * prompt — mirroring the real CLI, where the caret is present whenever a prompt
+ * field is open and only vanishes in menus that have none. Whether the cursor is
+ * actually drawn is a render-time choice (the "cursor" toggle).
+ */
+function tagTypingFrames(frames, input, detectFromContent) {
+    for (const f of frames) {
+        f.isTyping = false;
+        f.typedChars = 0;
+    }
+    const n = frames.length;
+    const haveTimes = n > 0 && frames[0].startMs !== undefined;
+    if (input && input.length && haveTimes) {
+        let j = 0;
+        for (const [t, count] of input) {
+            while (j < n && frames[j].startMs < t)
+                j++;
+            const k = j < n ? j : n - 1;
+            frames[k].typedChars = (frames[k].typedChars ?? 0) + count;
+            frames[k].isTyping = true;
+        }
+    }
+    else if (detectFromContent) {
+        let prevCaretCol = -1;
+        let prevHadText = false;
+        for (const f of frames) {
+            const box = findInputBox(f.grid);
+            if (box && box.hasText) {
+                if (prevHadText && box.caretCol > prevCaretCol) {
+                    f.typedChars = box.caretCol - prevCaretCol;
+                    f.isTyping = true;
+                }
+                prevCaretCol = box.caretCol;
+                prevHadText = true;
+            }
+            else {
+                prevHadText = false;
+                prevCaretCol = -1;
+            }
+        }
+    }
+    // Place the prompt cursor wherever an input box is open — not only while
+    // typing. The block then tracks the end of typed text and rests in the empty
+    // prompt after a submit, and is absent on frames with no prompt field.
+    for (const f of frames) {
+        const box = findInputBox(f.grid);
+        if (box)
+            f.caret = { row: box.row, col: box.caretCol };
+    }
+}
+/**
+ * Replay a raw ANSI/VT byte stream and recover every meaningful on-screen frame.
+ *
+ * The Copilot CLI (like most full-screen TUIs) paints into the alternate screen
+ * buffer and discards it on exit, so reading the terminal once at the end only
+ * yields the post-exit shell screen. Instead we feed the stream in segments and
+ * snapshot the screen just *before* each sequence that wipes or replaces it,
+ * preserving the live TUI frames. Blank and consecutive-identical frames are
+ * dropped. The result always has at least one frame.
+ */
+async function extractFrames(data, opts) {
+    const text = typeof data === 'string' ? data : data.toString('utf8');
+    const theme = opts.theme ?? 'dark';
+    const term = new headless_1.Terminal({
+        cols: opts.cols,
+        rows: opts.rows,
+        allowProposedApi: true,
+        scrollback: 0,
+    });
+    const write = (chunk) => new Promise((resolve) => {
+        if (chunk.length === 0)
+            return resolve();
+        term.write(chunk, () => resolve());
+    });
+    const boundaries = findBoundaries(text);
+    const raw = [];
+    let inAlt = false;
+    let cursor = 0;
+    let byteOffset = 0;
+    for (const b of boundaries) {
+        // Write everything up to (but not including) the boundary, then snapshot the
+        // screen as it stands right before it gets wiped or swapped away.
+        const seg = text.slice(cursor, b.start);
+        await write(seg);
+        byteOffset += Buffer.byteLength(seg, 'utf8');
+        raw.push({ grid: readGrid(term, opts.cols, opts.rows, theme), inAlt, endByte: byteOffset });
+        cursor = b.start;
+        if (b.kind === 'enter')
+            inAlt = true;
+        else if (b.kind === 'leave')
+            inAlt = false;
+    }
+    const tail = text.slice(cursor);
+    await write(tail);
+    byteOffset += Buffer.byteLength(tail, 'utf8');
+    raw.push({ grid: readGrid(term, opts.cols, opts.rows, theme), inAlt, endByte: byteOffset });
+    term.dispose();
+    // Drop blanks and collapse runs of identical screens (in-place repaints).
+    const kept = [];
+    let lastSig = '';
+    for (const f of raw) {
+        if (isBlank(f.grid))
+            continue;
+        const sig = signature(f.grid);
+        if (sig === lastSig) {
+            // Same screen as the kept one; keep the richer alt tag if this is alt.
+            if (f.inAlt && kept.length)
+                kept[kept.length - 1].inAlt = true;
+            continue;
+        }
+        lastSig = sig;
+        kept.push(f);
+    }
+    if (kept.length === 0) {
+        // Everything was blank — return the final screen so callers never get [].
+        kept.push(raw[raw.length - 1]);
+    }
+    // Attach timing when capture checkpoints were provided. A kept frame's
+    // appearance time is the moment its content finished streaming in (its end
+    // byte offset). Because we keep the *first* of a collapsed run and drop
+    // blanks, durations computed from consecutive kept starts automatically fold
+    // held/blank gaps into the preceding visible frame.
+    if (opts.timing && opts.timing.length) {
+        const starts = kept.map((f) => (0, timing_1.timeAtOffset)(opts.timing, f.endByte));
+        const endMs = (0, timing_1.timeAtOffset)(opts.timing, byteOffset);
+        const durations = (0, animation_1.frameDurations)(starts, endMs);
+        for (let i = 0; i < kept.length; i++) {
+            kept[i].startMs = starts[i];
+            kept[i].durationMs = durations[i];
+        }
+    }
+    // Strip the internal byte-offset bookkeeping from the public result.
+    const out = kept.map((f) => {
+        const frame = { grid: f.grid, inAlt: f.inAlt };
+        if (f.startMs !== undefined)
+            frame.startMs = f.startMs;
+        if (f.durationMs !== undefined)
+            frame.durationMs = f.durationMs;
+        return frame;
+    });
+    // Tag user-typing frames and place the prompt caret. Keystroke data (when
+    // present) is correlated to the paints it produced; otherwise typing is
+    // inferred from input-box growth unless that fallback is disabled.
+    tagTypingFrames(out, opts.input, opts.detectTypingFromContent ?? true);
+    return out;
+}
+function isBlankCell(c) {
+    return c.char.trim() === '' && c.bg === null && !c.inverse;
+}
+/** Count cells that carry visible content (a glyph, a background, or inverse). */
+function richness(grid) {
+    let n = 0;
+    for (const line of grid.lines)
+        for (const c of line)
+            if (!isBlankCell(c))
+                n++;
+    return n;
+}
+/**
+ * Pick a frame from {@link extractFrames}. With no `which`, returns the last
+ * *settled* full-screen (alternate-buffer) frame: starting at the final alt
+ * frame it walks back to the last local content peak, stepping over the exit
+ * "teardown" tail (the quit prompt and half-erased screen) so the default is
+ * the screen the user held on, not the frame mid-exit. Falls back to the last
+ * frame for plain, non-alt streams. `which` is 1-based; negative counts from
+ * the end (-1 = last).
+ */
+function chooseFrame(frames, which) {
+    if (frames.length === 0) {
+        return { grid: { cols: 0, rows: 0, lines: [] }, index: 0 };
+    }
+    let index;
+    if (which === undefined) {
+        const altIdx = [];
+        for (let i = 0; i < frames.length; i++)
+            if (frames[i].inAlt)
+                altIdx.push(i);
+        if (altIdx.length) {
+            // From the final alt frame, walk back to the last local content peak.
+            let p = altIdx.length - 1;
+            while (p > 0 &&
+                richness(frames[altIdx[p - 1]].grid) > richness(frames[altIdx[p]].grid)) {
+                p--;
+            }
+            // Only fall back to that peak if the capture ended collapsed — i.e. the
+            // TUI was torn down on exit (a `ctrl+c again to exit` prompt, then a
+            // half-erased screen). For a clean final paint, keep the last frame.
+            const last = altIdx.length - 1;
+            const collapsed = richness(frames[altIdx[last]].grid) <
+                richness(frames[altIdx[p]].grid) * 0.5;
+            index = altIdx[collapsed ? p : last];
+        }
+        else {
+            index = frames.length - 1;
+        }
+    }
+    else if (which < 0) {
+        index = frames.length + which;
+    }
+    else {
+        index = which - 1;
+    }
+    index = Math.max(0, Math.min(frames.length - 1, index));
+    return { grid: frames[index].grid, index };
+}
+/**
+ * Strip erase-to-end-of-line background "bleed" from a frame.
+ *
+ * Terminals resolve `ESC[K` (and trailing SGR background fills) against the
+ * *physical* terminal width, which is almost always wider than a TUI's actual
+ * content. The Copilot CLI input box is the canonical example: its border rows
+ * stop at the content width, but the focused interior row paints its background
+ * to the real right edge. Replayed in a wide terminal (the GUI defaults to 120
+ * cols) that bar overshoots the rest of the UI, so the prompt input looks too
+ * long.
+ *
+ * This clamps the grid to its inked content width — the rightmost *visible*
+ * glyph anywhere in the grid — dropping trailing cells that carry only a
+ * background. Background bars that sit within the inked width (selection
+ * highlights, status bars, the input-box interior up to its border) are
+ * untouched; only the erase-bleed past the content is removed. Returns a new
+ * grid and never mutates the input; it is a no-op when content already fills
+ * the width (so it can't shrink a legitimately full-width screen).
+ */
+function trimBackgroundBleed(grid) {
+    let inkedCols = 0;
+    for (const row of grid.lines) {
+        for (const cell of row) {
+            if (cell.char.trim() !== '') {
+                inkedCols = Math.max(inkedCols, cell.col + Math.max(1, cell.width));
+            }
+        }
+    }
+    if (inkedCols <= 0 || inkedCols >= grid.cols)
+        return grid;
+    const lines = grid.lines.map((row) => row.filter((cell) => cell.col < inkedCols));
+    return { cols: inkedCols, rows: grid.rows, lines };
+}
+/** A short one-line text preview of a frame, for listing. */
+function framePreview(grid) {
+    for (const line of grid.lines) {
+        const text = line
+            .map((c) => c.char)
+            .join('')
+            .replace(/\s+/g, ' ')
+            .trim();
+        if (text)
+            return text.length > 56 ? `${text.slice(0, 55)}…` : text;
+    }
+    return '(blank)';
+}
+function readLine(line, cols, theme) {
+    const cells = [];
+    if (!line)
+        return cells;
+    for (let x = 0; x < cols; x++) {
+        const cell = line.getCell(x);
+        if (!cell)
+            continue;
+        const width = cell.getWidth();
+        // Width 0 is the trailing half of a wide glyph; skip it (the leading
+        // cell already carries the character and a width of 2).
+        if (width === 0)
+            continue;
+        let char = cell.getChars();
+        if (char === '')
+            char = ' ';
+        const underline = cell.isUnderline() !== 0;
+        const ext = underline ? readUnderline(cell, theme) : undefined;
+        cells.push({
+            char,
+            col: x,
+            width,
+            fg: resolveColor(cell, 'fg', theme),
+            bg: resolveColor(cell, 'bg', theme),
+            bold: cell.isBold() !== 0,
+            italic: cell.isItalic() !== 0,
+            underline,
+            underlineStyle: ext?.style,
+            underlineColor: ext?.color ?? null,
+            dim: cell.isDim() !== 0,
+            strike: cell.isStrikethrough() !== 0,
+            inverse: cell.isInverse() !== 0,
+            invisible: cell.isInvisible() !== 0,
+        });
+    }
+    return cells;
+}
+// Extended-underline maps style index → name. xterm reports a plain `CSI 4 m`
+// as style 1, then 2..5 for double/curly/dotted/dashed (from `CSI 4 : n m`).
+const UNDERLINE_STYLES = [
+    'single', // 0 — shouldn't occur while underlined; guarded to single
+    'single', // 1
+    'double', // 2
+    'curly', // 3
+    'dotted', // 4
+    'dashed', // 5
+];
+// xterm color packing: the mode lives in bits 24–25, the value in the low bits.
+const CM_MASK = 0x03000000;
+const CM_P16 = 0x01000000;
+const CM_P256 = 0x02000000;
+const CM_RGB = 0x03000000;
+function decodePackedColor(packed, theme) {
+    const mode = packed & CM_MASK;
+    if (mode === CM_RGB)
+        return (0, palette_1.packedRgbToHex)(packed & 0xffffff);
+    if (mode === CM_P256 || mode === CM_P16)
+        return (0, palette_1.paletteToHex)(packed & 0xff, theme);
+    return null; // default → render as the text color
+}
+/**
+ * Read the extended underline style and color for a cell.
+ *
+ * The public @xterm/headless v5.5 cell API only exposes `isUnderline(): number`,
+ * which is 1 for *every* underline variant — it cannot distinguish curly/double/
+ * dotted/dashed or a distinct underline color. That information is held in the
+ * cell's internal extended attributes (`IExtendedAttrs.underlineStyle` /
+ * `underlineColor`), so we read it through a guarded structural cast and fall
+ * back to a plain single underline if a future xterm changes the shape.
+ */
+function readUnderline(cell, theme) {
+    const ext = cell.extended;
+    const styleNum = typeof ext?.underlineStyle === 'number' ? ext.underlineStyle : 1;
+    const style = UNDERLINE_STYLES[styleNum] ?? 'single';
+    const color = typeof ext?.underlineColor === 'number' && ext.underlineColor !== 0
+        ? decodePackedColor(ext.underlineColor, theme)
+        : null;
+    return { style, color };
+}
+function resolveColor(cell, which, theme) {
+    if (which === 'fg') {
+        if (cell.isFgDefault())
+            return null;
+        if (cell.isFgRGB())
+            return (0, palette_1.packedRgbToHex)(cell.getFgColor());
+        if (cell.isFgPalette())
+            return (0, palette_1.paletteToHex)(cell.getFgColor(), theme);
+        return null;
+    }
+    if (cell.isBgDefault())
+        return null;
+    if (cell.isBgRGB())
+        return (0, palette_1.packedRgbToHex)(cell.getBgColor());
+    if (cell.isBgPalette())
+        return (0, palette_1.paletteToHex)(cell.getBgColor(), theme);
+    return null;
+}