tmux-ide 2.7.0 → 2.9.0-beta.11

package/packages/daemon/dist/tui/mirror/pane-mirror.js

@@ -0,0 +1,584 @@
+/**
+ * A pane mirror: a headless terminal emulator fed by tmux control-mode
+ * `%output` bytes, exposing a renderable grid snapshot.
+ *
+ * @xterm/headless is xterm.js without a DOM — a full VT parser (SGR, cursor,
+ * alt-screen, scroll regions) maintaining a cell buffer. We write raw pane
+ * bytes in and read the grid out; the TUI draws the snapshot. This is the
+ * seam between "tmux owns the PTYs" and "tmux-ide owns the pixels".
+ *
+ * Fidelity notes (M21.6 — the current truth):
+ *  - Colors resolve to packed 0xRRGGBB here (256-palette + truecolor + the
+ *    16 base colors). The source grid remains unchanged; an optional renderer
+ *    palette projection applies the live OpenTUI defaults while preserving
+ *    explicit ANSI/truecolor values.
+ *  - Attributes carried, mapped onto OpenTUI's TextAttributes bitmask:
+ *    bold, dim, italic, underline, blink, hidden, strikethrough. INVERSE is NOT set as
+ *    an attribute — it renders as a fg/bg SWAP in the blit (a framebuffer cell
+ *    carrying the INVERSE bit does not flush as reverse; see blit.ts), so it
+ *    composes with the selection/cursor swaps.
+ *  - Attributes DROPPED (no representation downstream): overline (xterm exposes
+ *    `isOverline()`, OpenTUI has no overline attribute); extended underline
+ *    STYLES (curly/double/dotted) and underline COLOR (not on xterm-headless's
+ *    public cell API, and OpenTUI has only a single underline). Blink is passed
+ *    through as the BLINK attribute — the real terminal decides whether to honor
+ *    it (most modern terminals ignore or soften it); we don't down-map it.
+ *  - CURSOR: not painted into the grid. The focused pane drives the REAL
+ *    hardware cursor via the renderer (position + DECTCEM hide/show + DECSCUSR
+ *    shape/blink, read through {@link cursorState}); unfocused panes get a quiet
+ *    painted marker. See pane-surface.tsx.
+ *  - Wide glyphs (CJK, emoji) occupy one cell + a zero-width spacer; the
+ *    spacer is skipped so runs stay grid-aligned.
+ *  - `scrollback` is real (5000 lines): `snapshot(offset)` renders `offset`
+ *    lines above the live viewport, `scrollbackDepth()` says how far back
+ *    a pane can go.
+ */
+import { Terminal } from "@tmux-ide/xterm-headless";
+import { Unicode11Addon } from "@xterm/addon-unicode11";
+import { writeCell, writeContinuation, SPACE_CODE, } from "./blit.js";
+import { AckWriter } from "./ack-writer.js";
+import { extractSelection } from "./selection.js";
+import { XTERM_PALETTE } from "./ansi-palette.js";
+import { createWidgetMarkerByteWatcher, detectWidgetMarker, } from "@tmux-ide/contracts";
+export { XTERM_PALETTE } from "./ansi-palette.js";
+/** OpenTUI TextAttributes bit values (kept literal to avoid the dep here). */
+const ATTR_BOLD = 1;
+const ATTR_DIM = 2;
+const ATTR_ITALIC = 4;
+const ATTR_UNDERLINE = 8;
+const ATTR_BLINK = 16;
+const ATTR_INVERSE = 32;
+const ATTR_HIDDEN = 64;
+const ATTR_STRIKETHROUGH = 128;
+/** True iff the shadow slice at `off` equals `data` (an exact per-row cell-data
+ *  compare — no hash, so no collision can strand a stale row). Early-exits on the
+ *  first differing u32. */
+function shadowMatches(shadow, off, data) {
+    if (data.length + off > shadow.length)
+        return false;
+    for (let k = 0; k < data.length; k++) {
+        if (shadow[off + k] !== data[k])
+            return false;
+    }
+    return true;
+}
+export class PaneMirror {
+    term;
+    /** Rich-widget detection stays off the hot path until the raw byte stream
+     *  contains the versioned sentinel. While a widget is active we rescan after
+     *  each committed write so Ctrl-C/ED3 restores the terminal immediately. */
+    widgetBytes = createWidgetMarkerByteWatcher();
+    widgetScanPending = false;
+    activeWidget = null;
+    /** Ack-paced writes (M21.5): xterm's `write` is async with a completion
+     *  callback; chunks arriving mid-parse buffer here and follow as ONE joined
+     *  write from the callback, so parser backpressure never queues unbounded
+     *  entries — and never stalls the control-channel reader loop feeding us. */
+    /** Fires when a paced write has actually PARSED into the grid — the dirty
+     *  signal the render tick must re-arm on (enqueue-time dirty can be consumed
+     *  before the parse lands, dropping the final frame; see AckWriter.onAck). */
+    onParsed;
+    writer = new AckWriter((data, done) => this.term.write(data, done), () => {
+        if (this.widgetScanPending || this.activeWidget !== null)
+            this.refreshWidgetMarker();
+        this.onParsed?.();
+    });
+    cols;
+    rows;
+    // ── Incremental-blit state (M21.4) ─────────────────────────────────────────
+    /** Per-pane content version — bumps on any grid change (parse/scroll/resize).
+     *  A surface gates its walk on this: an unchanged pane never re-reads. */
+    _version = 0;
+    /** Net forward scrolls (line count) since the last blit — drives the shift
+     *  fast path. Counted from xterm's onScroll (which fires once per scrolled
+     *  line and keeps firing at the scrollback cap, unlike the saturating payload). */
+    _pendingScroll = 0;
+    // ── Absolute-line stability (M25.6) ────────────────────────────────────────
+    /** Lines TRIMMED off the top of the scrollback (monotonic): once viewportY
+     *  saturates at the scrollback cap, each further scroll rotates one line out
+     *  and every retained line's absolute index drops by one. An absolute-space
+     *  consumer (the drag selection) records `lineTrim()` when it anchors and
+     *  subtracts the delta later, so its anchor keeps naming the same content.
+     *  Detected as "onScroll fired but viewportY did not grow". A scrollback
+     *  clear (`clear-history` / ED3) collapses viewportY instead — that index
+     *  shift is NOT counted; stale absolute cells then clamp into the buffer
+     *  (the selection was over content that no longer exists anyway). */
+    _trimmed = 0;
+    _lastViewportY = 0;
+    /** The alt/normal buffer swapped (`?1049h/l`) — the whole grid is new. */
+    _bufferSwapped = false;
+    /** Shadow of the last-blitted rows' raw xterm cell data (`_line._data`,
+     *  cols×3 u32/row) — an EXACT compare finds changed rows with no getter cost
+     *  and no hash-collision risk. Null until the capability probe or a resize. */
+    _shadow = null;
+    _shadowValid = false;
+    /** `_line._data` reachable (xterm-headless internal, pinned 6.0). When false,
+     *  the blit degrades to a full repaint every walk — correct, just not
+     *  incremental. */
+    _incremental = true;
+    constructor(cols, rows, scrollback = 5000) {
+        this.cols = cols;
+        this.rows = rows;
+        this.term = new Terminal({ cols, rows, allowProposedApi: true, scrollback });
+        // Unicode 6 classifies many modern emoji as one cell while OpenTUI/the host
+        // terminal paints them as two. Pin both renderers to xterm's Unicode 11
+        // width provider so the parser grid and the pixels advance identically.
+        this.term.loadAddon(new Unicode11Addon());
+        this.term.unicode.activeVersion = "11";
+        this.term.onWriteParsed(() => this._version++);
+        this.term.onScroll(() => {
+            this._pendingScroll++;
+            // Trim detection (M25.6): below the cap each scroll grows viewportY by
+            // one; at the cap it stays put and the oldest line rotated out.
+            const vy = this.term.buffer.active.viewportY;
+            if (vy === this._lastViewportY)
+                this._trimmed++;
+            else
+                this._lastViewportY = vy;
+        });
+        this.term.buffer.onBufferChange(() => {
+            this._bufferSwapped = true;
+            this._version++;
+        });
+        // Capability probe (once): can we reach xterm's raw per-line cell data for
+        // the exact-compare dirty check? If not, the blit repaints in full.
+        const probe = this.term.buffer.active.getLine(0);
+        this._incremental = probe?._line?._data instanceof Uint32Array;
+    }
+    /** The per-pane content version (M21.4) — see {@link _version}. */
+    contentVersion() {
+        return this._version;
+    }
+    /**
+     * The live cursor: grid position + the app-driven DECTCEM visibility and
+     * DECSCUSR shape/blink (M21.6). Position is public (`cursorX/Y`); the mode
+     * state lives on xterm's internal coreService (no public getter), reached
+     * defensively — if the internal is absent the cursor stays visible as a block,
+     * which is the terminal default anyway. `style` is xterm's vocabulary
+     * (`block`/`underline`/`bar`); the renderer maps it.
+     */
+    cursorState() {
+        const buf = this.term.buffer.active;
+        const core = this.term._core;
+        const cs = core?.coreService;
+        const dec = cs?.decPrivateModes;
+        return {
+            x: buf.cursorX,
+            y: buf.cursorY,
+            hidden: cs?.isCursorHidden === true,
+            style: dec?.cursorStyle ?? this.term.options.cursorStyle ?? "block",
+            blink: dec?.cursorBlink ?? this.term.options.cursorBlink ?? false,
+        };
+    }
+    /** Feed raw pane bytes (UTF-8) from a control-mode %output event. */
+    write(data) {
+        // Normalize to bytes so the pacer coalesces freely; a JS string encodes to
+        // the same UTF-8 xterm would have decoded it from.
+        const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+        if (this.widgetBytes.observe(bytes))
+            this.widgetScanPending = true;
+        this.writer.write(bytes);
+    }
+    resize(cols, rows) {
+        this.cols = cols;
+        this.rows = rows;
+        this.term.resize(cols, rows);
+        // Geometry changed — the shadow and any prior framebuffer are stale; the
+        // next blit must repaint in full (the surface also forces it on its resize).
+        this._shadow = null;
+        this._pendingScroll = 0;
+        this._bufferSwapped = false;
+        // Reflow moved viewportY without scrolls — re-baseline the trim detector so
+        // the first post-resize scroll isn't miscounted as a cap rotation. (Reflow
+        // also re-indexes wrapped lines; a mid-resize drag selection is approximate
+        // by nature and clamps safely.)
+        this._lastViewportY = this.term.buffer.active.viewportY;
+        this._version++;
+        if (this.activeWidget !== null)
+            this.refreshWidgetMarker();
+    }
+    /** Current in-band rich widget, or null. Detection runs only after the byte
+     *  gate trips; this accessor is therefore O(1) on every normal render tick. */
+    widgetMarker() {
+        return this.activeWidget;
+    }
+    refreshWidgetMarker() {
+        this.widgetScanPending = false;
+        this.activeWidget = detectWidgetMarker(this.widgetCellRows());
+    }
+    /** Cell-accurate buffer projection, including xterm's wrap bit. This is the
+     *  only representation from which a long, wrapped marker can be recovered. */
+    widgetCellRows() {
+        const buf = this.term.buffer.active;
+        const cell = buf.getNullCell();
+        const rows = [];
+        for (let y = 0; y < buf.length; y++) {
+            const line = buf.getLine(y);
+            if (!line) {
+                rows.push({ cells: [], wrapped: false });
+                continue;
+            }
+            const cells = [];
+            for (let x = 0; x < this.cols; x++) {
+                line.getCell(x, cell);
+                cells.push(cell.getWidth() === 0 ? "" : cell.getChars() || " ");
+            }
+            rows.push({ cells, wrapped: line.isWrapped });
+        }
+        return rows;
+    }
+    /** Monotonic count of lines trimmed off the scrollback top (M25.6) — the
+     *  absolute-line drift an anchored consumer must subtract. See {@link _trimmed}. */
+    lineTrim() {
+        return this._trimmed;
+    }
+    /** Lines available above the live viewport (how far back scroll can go). */
+    scrollbackDepth() {
+        return this.term.buffer.active.viewportY;
+    }
+    /**
+     * The WHOLE buffer (scrollback + live viewport) as plain text lines, top→bottom
+     * — the search corpus. Read on demand (cheap; no per-frame cost). Uses xterm's
+     * `translateToString(true)` so wide-glyph spacers collapse and trailing blanks
+     * trim exactly the way the rendered snapshot rows do, keeping a match's column
+     * aligned between the search hit and the highlight injection. Line index `y` is
+     * absolute (0 = oldest scrollback line); the live viewport top sits at
+     * `scrollbackDepth()`, so a match at line `y` maps to visible row
+     * `y - (scrollbackDepth - scrollOffset)`.
+     */
+    bufferLines() {
+        const buf = this.term.buffer.active;
+        const out = [];
+        for (let y = 0; y < buf.length; y++) {
+            const line = buf.getLine(y);
+            out.push(line ? line.translateToString(true) : "");
+        }
+        return out;
+    }
+    /**
+     * Read a grid as rows of same-styled runs.
+     *
+     * @param scrollOffset Render this many lines above the live viewport
+     *   (clamped to the available scrollback). 0 = live view.
+     * @param withCursor Paint the cursor cell inverse (the focused pane).
+     * @param includeRows Serialize the styled rows. `false` returns only the
+     *   cursor/offset metadata (rows `[]`) — the framebuffer-blit path (M21.3)
+     *   reads cells via {@link blit} instead, so it skips the run rebuild entirely.
+     */
+    snapshot(scrollOffset = 0, withCursor = false, includeRows = true, palette) {
+        const buf = this.term.buffer.active;
+        const offset = Math.max(0, Math.min(scrollOffset, buf.viewportY));
+        if (!includeRows) {
+            return { rows: [], cursorX: buf.cursorX, cursorY: buf.cursorY, scrollOffset: offset };
+        }
+        const baseY = buf.viewportY - offset;
+        const live = offset === 0;
+        const rows = [];
+        const cell = buf.getNullCell();
+        for (let y = 0; y < this.rows; y++) {
+            const line = buf.getLine(baseY + y);
+            const runs = [];
+            if (line) {
+                let text = "";
+                let fg = null;
+                let bg = null;
+                let attrs = 0;
+                const isCursorRow = withCursor && live && y === buf.cursorY;
+                for (let x = 0; x < this.cols; x++) {
+                    line.getCell(x, cell);
+                    if (cell.getWidth() === 0)
+                        continue; // spacer half of a wide glyph
+                    let cellFg = null;
+                    if (cell.isFgRGB()) {
+                        const color = cell.getFgColor();
+                        cellFg = palette ? palette.resolveForeground(color) : color;
+                    }
+                    else if (cell.isFgPalette()) {
+                        const index = cell.getFgColor();
+                        cellFg = palette?.ansiForeground[index] ?? XTERM_PALETTE[index] ?? null;
+                    }
+                    let cellBg = null;
+                    if (cell.isBgRGB()) {
+                        const color = cell.getBgColor();
+                        cellBg = palette ? palette.resolveBackground(color) : color;
+                    }
+                    else if (cell.isBgPalette()) {
+                        const index = cell.getBgColor();
+                        cellBg = palette?.ansiBackground[index] ?? XTERM_PALETTE[index] ?? null;
+                    }
+                    let cellAttrs = 0;
+                    if (cell.isBold())
+                        cellAttrs |= ATTR_BOLD;
+                    if (cell.isDim())
+                        cellAttrs |= ATTR_DIM;
+                    if (cell.isItalic())
+                        cellAttrs |= ATTR_ITALIC;
+                    if (cell.isUnderline())
+                        cellAttrs |= ATTR_UNDERLINE;
+                    if (cell.isBlink())
+                        cellAttrs |= ATTR_BLINK;
+                    if (cell.isInverse())
+                        cellAttrs |= ATTR_INVERSE;
+                    if (cell.isInvisible())
+                        cellAttrs |= ATTR_HIDDEN;
+                    if (cell.isStrikethrough())
+                        cellAttrs |= ATTR_STRIKETHROUGH;
+                    // The cursor renders as an inverse cell in the focused, live pane.
+                    if (isCursorRow && x === buf.cursorX)
+                        cellAttrs ^= ATTR_INVERSE;
+                    if (text.length > 0 && (cellFg !== fg || cellBg !== bg || cellAttrs !== attrs)) {
+                        runs.push({ text, fg, bg, attributes: attrs });
+                        text = "";
+                    }
+                    fg = cellFg;
+                    bg = cellBg;
+                    attrs = cellAttrs;
+                    const chars = cell.getChars() || " ";
+                    text += chars;
+                    // A wide glyph fills two columns with one string; pad the run's
+                    // grid alignment by skipping the spacer in the next iteration
+                    // (handled by the getWidth()===0 check above).
+                }
+                if (text.length > 0)
+                    runs.push({ text, fg, bg, attributes: attrs });
+            }
+            rows.push(runs);
+        }
+        return { rows, cursorX: buf.cursorX, cursorY: buf.cursorY, scrollOffset: offset };
+    }
+    /**
+     * Blit the visible grid into a framebuffer's packed typed arrays — the
+     * native-feel render path, now INCREMENTAL (M21.4). Same cell semantics as
+     * {@link snapshot} (colors → `0xRRGGBB`, the OpenTUI attribute bitmask incl.
+     * blink, wide-glyph spacers). The cursor is NOT painted here (M21.6): the
+     * focused pane drives the real hardware cursor and the surface paints any
+     * unfocused marker. Only the rows that actually changed are rewritten:
+     *
+     *  - A **scroll fast path** (xterm `onScroll` counted forward-scroll lines)
+     *    shifts the already-correct pixels up with `copyWithin`, so a flood repaints
+     *    only the new bottom rows, not the whole grid.
+     *  - A **per-row exact compare** of xterm's raw cell data against a shadow finds
+     *    in-place changes (alt-screen redraws) with no getter cost; unchanged rows
+     *    are skipped (~78% of the blit cost is the writes we then avoid).
+     *  - `opts.full` repaints everything (first frame, resize, scrolled/searching
+     *    view), `opts.forceRows` repaints the caller's selection/search churn, and
+     *    the cursor's old+new rows always repaint (the overlay isn't in the shadow).
+     *
+     * `opts.dirtyRows` is filled with the rows written (the caller re-applies its
+     * post-passes there). `defaultFg`/`defaultBg` are packed `0xRRGGBB` for the
+     * terminal default. When the raw-cell-data internal is unreachable the blit
+     * degrades to a full repaint every call (still correct).
+     */
+    blit(buffers, width, height, scrollOffset, defaultFg, defaultBg, opts) {
+        const buf = this.term.buffer.active;
+        const offset = Math.max(0, Math.min(scrollOffset, buf.viewportY));
+        const baseY = buf.viewportY - offset;
+        const live = offset === 0;
+        const cell = buf.getNullCell();
+        const cols = Math.min(this.cols, width);
+        const rowLen = this.cols * 3; // xterm packs 3 u32 per cell (content/fg/bg)
+        // (Re)size the shadow to the current geometry; a fresh shadow is invalid, so
+        // the first blit after it repaints in full and fills it.
+        if (this._incremental) {
+            if (this._shadow === null || this._shadow.length !== rowLen * height) {
+                this._shadow = rowLen * height > 0 ? new Uint32Array(rowLen * height) : null;
+                this._shadowValid = false;
+            }
+        }
+        // A full repaint is forced on the first frame, a resize, a buffer swap, a
+        // scrolled/searching view (offset > 0 — the whole window is different), or
+        // when the incremental machinery is unavailable.
+        const full = opts.full ||
+            !live ||
+            this._bufferSwapped ||
+            !this._incremental ||
+            !this._shadowValid ||
+            this._shadow === null;
+        this._bufferSwapped = false;
+        // Scroll fast path: shift the already-correct pixels + shadow up so only the
+        // newly exposed bottom rows fall out of sync.
+        let shift = 0;
+        if (!full && this._pendingScroll > 0)
+            shift = Math.min(this._pendingScroll, height);
+        this._pendingScroll = 0;
+        if (shift > 0 && this._shadow) {
+            const w4 = width * 4;
+            buffers.char.copyWithin(0, shift * width, height * width);
+            buffers.fg.copyWithin(0, shift * w4, height * w4);
+            buffers.bg.copyWithin(0, shift * w4, height * w4);
+            buffers.attributes.copyWithin(0, shift * width, height * width);
+            this._shadow.copyWithin(0, shift * rowLen, height * rowLen);
+        }
+        const bottomDirtyFrom = full ? 0 : height - shift;
+        const dfR = (defaultFg >> 16) & 0xff;
+        const dfG = (defaultFg >> 8) & 0xff;
+        const dfB = defaultFg & 0xff;
+        const dbR = (defaultBg >> 16) & 0xff;
+        const dbG = (defaultBg >> 8) & 0xff;
+        const dbB = defaultBg & 0xff;
+        const forceRows = opts.forceRows && opts.forceRows.length ? opts.forceRows : null;
+        for (let y = 0; y < height; y++) {
+            const raw = this._incremental ? this.rowData(baseY, y) : null;
+            // Bounds guard (M23.5, D5): after a shrink xterm's reflow can leave a
+            // line's `_data` at a length ≠ cols×3; comparing or `set`ting it against
+            // the rowLen-strided shadow would read garbage / throw RangeError. Treat
+            // such a row as shadow-less: always repaint it, never write the shadow.
+            const data = raw !== null && raw.length === rowLen ? raw : null;
+            let dirty = full || y >= bottomDirtyFrom || data === null; // no shadow info for this row → always repaint
+            if (!dirty && this._shadow)
+                dirty = !shadowMatches(this._shadow, y * rowLen, data);
+            if (!dirty && forceRows) {
+                for (let i = 0; i < forceRows.length; i++)
+                    if (forceRows[i] === y) {
+                        dirty = true;
+                        break;
+                    }
+            }
+            if (!dirty)
+                continue;
+            this.blitRow(cell, buffers, y, baseY, width, cols, dfR, dfG, dfB, dbR, dbG, dbB, defaultFg, defaultBg, opts.graphemes, opts.palette);
+            if (this._shadow && data)
+                this._shadow.set(data, y * rowLen);
+            opts.dirtyRows.push(y);
+        }
+        if (this._incremental && this._shadow)
+            this._shadowValid = true;
+    }
+    /** The raw xterm cell data for visible row `y` (`cols`×3 u32), or null when the
+     *  row or the internal is unavailable. See the constructor's capability probe. */
+    rowData(baseY, y) {
+        if (y >= this.rows)
+            return null;
+        const line = this.term.buffer.active.getLine(baseY + y);
+        const data = line?._line?._data;
+        return data instanceof Uint32Array ? data : null;
+    }
+    /** Write one visible row's cells into the framebuffer (the M21.3 per-cell blit,
+     *  extracted so the incremental path repaints a single row). */
+    blitRow(cell, buffers, y, baseY, width, cols, dfR, dfG, dfB, dbR, dbG, dbB, defaultFg, defaultBg, graphemes, palette) {
+        const buf = this.term.buffer.active;
+        const line = y < this.rows ? buf.getLine(baseY + y) : null;
+        for (let x = 0; x < width; x++) {
+            const idx = y * width + x;
+            if (!line || x >= cols) {
+                writeCell(buffers, idx, SPACE_CODE, null, null, 0, dfR, dfG, dfB, dbR, dbG, dbB);
+                continue;
+            }
+            line.getCell(x, cell);
+            if (cell.getWidth() === 0) {
+                // Spacer half of the preceding wide glyph — inherit its colors.
+                writeContinuation(buffers, idx);
+                continue;
+            }
+            let fg = null;
+            if (cell.isFgRGB()) {
+                const color = cell.getFgColor();
+                fg = palette ? palette.resolveForeground(color) : color;
+            }
+            else if (cell.isFgPalette()) {
+                const index = cell.getFgColor();
+                fg = palette?.ansiForeground[index] ?? XTERM_PALETTE[index] ?? null;
+            }
+            let bg = null;
+            if (cell.isBgRGB()) {
+                const color = cell.getBgColor();
+                bg = palette ? palette.resolveBackground(color) : color;
+            }
+            else if (cell.isBgPalette()) {
+                const index = cell.getBgColor();
+                bg = palette?.ansiBackground[index] ?? XTERM_PALETTE[index] ?? null;
+            }
+            let attrs = 0;
+            if (cell.isBold())
+                attrs |= ATTR_BOLD;
+            if (cell.isDim())
+                attrs |= ATTR_DIM;
+            if (cell.isItalic())
+                attrs |= ATTR_ITALIC;
+            if (cell.isUnderline())
+                attrs |= ATTR_UNDERLINE;
+            if (cell.isBlink())
+                attrs |= ATTR_BLINK;
+            if (cell.isInvisible())
+                attrs |= ATTR_HIDDEN;
+            if (cell.isStrikethrough())
+                attrs |= ATTR_STRIKETHROUGH;
+            // Reverse video (app INVERSE) renders as a fg/bg SWAP, not the INVERSE
+            // attribute bit — a framebuffer cell carrying that bit does not flush as
+            // reverse (see blit.ts). Resolve nulls to the defaults first so
+            // default-on-default inverts to defaultBg-on-defaultFg.
+            const inverted = !!cell.isInverse();
+            const chars = cell.getChars();
+            const codepoint = chars ? (chars.codePointAt(0) ?? SPACE_CODE) : SPACE_CODE;
+            const renderedFg = inverted ? (bg === null ? defaultBg : bg) : fg;
+            const renderedBg = inverted ? (fg === null ? defaultFg : fg) : bg;
+            writeCell(buffers, idx, codepoint, renderedFg, renderedBg, attrs, dfR, dfG, dfB, dbR, dbG, dbB);
+            // A grapheme wider than its base codepoint (ZWJ/flag emoji, combining marks)
+            // can't live in a single u32 — record it for the native setCell re-write.
+            if (graphemes && chars.length > (codepoint > 0xffff ? 2 : 1)) {
+                // Use the exact colors written above. The PaneSurface post-pass replaces
+                // this cell with `setCell`; carrying the source colors here would undo
+                // inverse video only for combined/ZWJ graphemes.
+                graphemes.push({ x, y, chars, fg: renderedFg, bg: renderedBg, attrs });
+            }
+        }
+    }
+    /**
+     * The visible rows as plain text (trailing blanks trimmed, wide spacers
+     * collapsed) — the on-demand read the OSC52 copy path uses when the blit path
+     * has omitted the styled rows. `scrollOffset` matches {@link snapshot}.
+     */
+    visibleRowTexts(scrollOffset = 0) {
+        const buf = this.term.buffer.active;
+        const offset = Math.max(0, Math.min(scrollOffset, buf.viewportY));
+        const baseY = buf.viewportY - offset;
+        const out = [];
+        for (let y = 0; y < this.rows; y++) {
+            const line = buf.getLine(baseY + y);
+            out.push(line ? line.translateToString(true) : "");
+        }
+        return out;
+    }
+    /**
+     * Extract the text of an ORDERED absolute-line range (M25.6) — the release
+     * path of a selection that may span far beyond the viewport. Each buffer
+     * line reads via `translateToString(true)` — the SAME trim/collapse as
+     * {@link visibleRowTexts} (wide-glyph spacers collapse, trailing blanks trim)
+     * — and the columns/joining go through {@link extractSelection}, so a
+     * selection that happens to fit one screen extracts byte-identically to the
+     * old visible-rows path. Wrapped lines stay separate visual rows joined with
+     * "\n", exactly as the on-screen copy always has.
+     *
+     * `maxBytes` bounds the string BUILT here: accumulation stops once the raw
+     * line total strictly exceeds it, so a runaway span never materializes tens
+     * of MB — the caller's clipboard cap (which refuses anything over the limit)
+     * still sees an over-limit byte count and refuses honestly.
+     */
+    extractAbsoluteText(start, end, maxBytes) {
+        const buf = this.term.buffer.active;
+        const last = buf.length - 1;
+        if (last < 0 || end.row < 0 || start.row > last)
+            return "";
+        const lo = Math.max(0, Math.min(start.row, last));
+        const hi = Math.max(0, Math.min(end.row, last));
+        const rowTexts = [];
+        let bytes = 0;
+        for (let y = lo; y <= hi; y++) {
+            const line = buf.getLine(y);
+            const text = line ? line.translateToString(true) : "";
+            rowTexts.push(text);
+            bytes += Buffer.byteLength(text, "utf8") + 1; // +1 for the joining "\n"
+            if (bytes > maxBytes)
+                break;
+        }
+        // Shift the range to the accumulated slice. A clamped start selects from
+        // column 0 (its true start line is gone/off-buffer); a clamped or
+        // byte-truncated end extends to its last line's end (Infinity clamps to
+        // the row length inside rowSelectionRange).
+        const lastRowAbs = lo + rowTexts.length - 1;
+        return extractSelection(rowTexts, { row: 0, col: start.row === lo ? start.col : 0 }, { row: rowTexts.length - 1, col: lastRowAbs === end.row ? end.col : Infinity });
+    }
+    dispose() {
+        this.term.dispose();
+    }
+}