@tiens.nguyen/gu-cli 1.0.686

package/terminal-viewport.mjs

@@ -0,0 +1,602 @@
+/**
+ * App-owned scrollback for the `gu` terminal (task #141, second attempt).
+ *
+ * WHY THIS EXISTS. A bottom bar cannot survive the user scrolling as long as SCROLLING BELONGS
+ * TO THE TERMINAL: it repaints its own scrollback over the whole window and never tells the
+ * application. The way out is not the alternate screen — it is taking the wheel. With mouse
+ * reporting on, a wheel notch arrives as an INPUT EVENT and the terminal does not move, so the
+ * application decides what the window shows. Keep every printed line in a buffer, paint the
+ * slice the user has scrolled to, and the reserved bottom rows never move.
+ *
+ * That is exactly why an app that does this can offer "jump to bottom": it knows where you are.
+ *
+ * The view FOLLOWS THE BOTTOM: anything printed brings it home first, so scrolling up is the
+ * only way to leave the live tail — and the "jump to bottom" line exists precisely for the
+ * moments when you have.
+ *
+ * Everything here is pure — a buffer plus arithmetic — so the scroll behaviour is testable
+ * without a terminal. The REPL owns the mouse, the writes, and when to render.
+ */
+import { charWidth } from "./terminal-layout.mjs";
+
+/**
+ * The printed transcript, as physical lines.
+ *
+ * `append` takes raw output exactly as it was written to stdout: text may arrive in fragments
+ * with no trailing newline (a streamed answer), so the last line stays OPEN until its newline
+ * lands. Carriage returns rewrite the open line, which is how in-place progress text behaves.
+ * ANSI colour is kept — it is what the line looked like.
+ */
+export function createTranscript({ max = 20000 } = {}) {
+  // Colour is kept; anything that MOVES or ERASES is dropped. A recorded line is replayed
+  // verbatim when the user scrolls back, so a stray ESC[2A in it would move the caret and
+  // scramble the repaint — the line has to be inert text.
+  const sanitize = (s) =>
+    String(s)
+      .replace(/\x1b\[[0-9;?]*[A-LN-Za-ln-z]/g, "") // every CSI except SGR ("m")
+      .replace(/\x1b[78]/g, "")                      // DECSC / DECRC
+      .replace(/\x1b\][^\x07\x1b]*(\x07|\x1b\\)/g, ""); // OSC (title sets)
+
+  /** @type {string[]} */
+  let lines = [""];
+  let total = 0; // lines that have scrolled out of the buffer, so line numbers stay meaningful
+
+  const trim = () => {
+    if (lines.length <= max) return;
+    const drop = lines.length - max;
+    lines = lines.slice(drop);
+    total += drop;
+  };
+
+  return {
+    append(text) {
+      const s = sanitize(text ?? "");
+      if (!s) return;
+      for (const ch of s) {
+        if (ch === "\n") lines.push("");
+        else if (ch === "\r") lines[lines.length - 1] = "";
+        else lines[lines.length - 1] += ch;
+      }
+      trim();
+    },
+    /** All lines, oldest first. The last one may still be open (no newline yet). */
+    lines: () => lines,
+    /** How many lines are available to scroll through. */
+    length: () => lines.length,
+    dropped: () => total,
+    /**
+     * Replace recorded lines [fromAbs..toAbs] (ABSOLUTE indices, i.e. including lines already
+     * dropped) with `next`. The one mutation the transcript allows, and it exists for exactly
+     * one reason: a printed block that can be expanded and collapsed in place. Absolute
+     * indices because the buffer trims from the front, so a stored position must survive that.
+     * Returns the new absolute end, or null when the range has scrolled out of the buffer.
+     */
+    replaceRange(fromAbs, toAbs, next) {
+      const from = fromAbs - total;
+      const to = toAbs - total;
+      if (from < 0 || to >= lines.length || from > to) return null;
+      lines.splice(from, to - from + 1, ...next.map(sanitize));
+      trim();
+      return fromAbs + next.length - 1;
+    },
+    clear() {
+      lines = [""];
+      total = 0;
+    },
+  };
+}
+
+/**
+ * Wrap ONE recorded line into the display rows a terminal would soft-wrap it into.
+ *
+ * The transcript holds logical lines; the terminal wrapped the long ones when they were first
+ * printed. A repaint has to reproduce that or the text is simply lost (a clip drops everything
+ * past the right edge) AND the arithmetic drifts, because one logical line can be three rows on
+ * screen. Colour is carried onto continuation rows so a wrapped coloured line stays coloured.
+ *
+ * Counted in COLUMNS by code point (charWidth): iterating UTF-16 units cut emoji in half at a
+ * row boundary and mis-measured every wide character, so the wrap fell out of step with the
+ * terminal's own — which is what makes a repaint lose a line.
+ */
+export function wrapVisible(line, width) {
+  const w = Math.max(1, width);
+  const rows = [];
+  let row = "";
+  let seen = 0;
+  let sgr = ""; // the colour state to re-open on the next row
+  const chars = [...line];
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === "\x1b") {
+      const m = /^\x1b\[[0-9;]*m/.exec(chars.slice(i).join(""));
+      if (m) {
+        row += m[0];
+        sgr = m[0] === "\x1b[0m" ? "" : sgr + m[0];
+        i += [...m[0]].length - 1;
+        continue;
+      }
+    }
+    const cw = charWidth(chars[i]);
+    // A wide character that would straddle the edge moves down whole, exactly as the terminal
+    // does — leaving the last cell of the row blank rather than splitting the glyph.
+    if (seen + cw > w) {
+      rows.push(row);
+      row = sgr;
+      seen = 0;
+    }
+    row += chars[i];
+    seen += cw;
+  }
+  rows.push(row);
+  return rows;
+}
+
+/** Every recorded line as the display rows the screen actually shows. */
+export function displayRows(lines, width) {
+  const out = [];
+  for (const l of lines) for (const r of wrapVisible(l, width)) out.push(r);
+  return out;
+}
+
+/**
+ * For every display row, the index of the recorded line it came from.
+ *
+ * The screen and the transcript do not agree on what a "row" is: one long line is several
+ * rows once wrapped. Anything that has to turn a CLICKED ROW back into a piece of content —
+ * expanding a printed thought block (task #148) — needs that correspondence, and computing it
+ * from the same wrapping the viewport uses is the only way it stays right at every width.
+ */
+export function displayRowOwners(lines, width) {
+  const out = [];
+  lines.forEach((l, i) => {
+    for (let r = 0; r < wrapVisible(l, width).length; r++) out.push(i);
+  });
+  return out;
+}
+
+/**
+ * The FIRST display row on screen, given how many rows the transcript is painted into.
+ *
+ * `height` IS NOT ALWAYS THE HEIGHT OF THE SCROLLING AREA, and that is the whole reason this
+ * is one named function rather than a line repeated at each call site. An in-place block drawn
+ * UNDER the transcript — the live "Thinking… (12s)" status, which is deliberately never
+ * recorded in the transcript — owns the rows it covers, and the transcript stops above them.
+ * Hand this the full height while such a block is up and every screen row resolves to a line
+ * that many rows too early: hovering a printed thought highlighted the block a few lines above
+ * the pointer, and a repaint dropped transcript text on top of the thinking line.
+ *
+ * `total` is the number of display rows the transcript has (displayRowOwners(...).length).
+ *
+ * `offset` IS HOW FAR THE USER HAS SCROLLED BACK, counted from the bottom exactly as
+ * viewportSlice counts it — and it must be, because these two answer the same question from
+ * opposite ends: viewportSlice says which rows get PAINTED, this says which row the top of the
+ * paint is. Defaulting it to 0 is what the live tail means, and every caller that only ever
+ * looks at the live tail can keep passing two arguments.
+ *
+ * IT USED TO TAKE NO OFFSET AT ALL, and that is the whole of the scrolled-back selection bug
+ * (reported 2026-09-01: "when i scroll up and copy the question it is not selected; if i scroll
+ * down to bottom it is allowed to select"). Every screen-row → transcript-row mapping in the
+ * REPL runs through here, so while scrolled back they all resolved to rows near the END of the
+ * transcript — the text at the live tail, not the text under the pointer. Rather than fix the
+ * arithmetic, the callers had been gated off with `!scrolledBack()`, which is why dragging up
+ * there highlighted nothing and copied nothing.
+ *
+ * Clamped the same way viewportSlice clamps, so a wheel spun past the top and this function
+ * cannot disagree about where the view actually stopped.
+ */
+export function firstVisibleRow(total, height, offset = 0) {
+  const h = Math.max(1, height);
+  const maxOffset = Math.max(0, total - h);
+  const clamped = Math.max(0, Math.min(Math.max(0, offset | 0), maxOffset));
+  return Math.max(0, total - h - clamped);
+}
+
+/**
+ * Which recorded line viewport row `row` (1-based) is showing — or -1 when that row holds no
+ * transcript (above the first line, or below the last one, where an in-place block lives).
+ *
+ * `offset` is the scroll position, as in firstVisibleRow: omit it for the live tail.
+ */
+export function lineAtViewportRow(owners, row, height, offset = 0) {
+  // ROWS ARE 1-BASED. Without this guard row 0 quietly resolves to the line one row ABOVE the
+  // top of the view — a real index, so nothing downstream can tell it was never on screen.
+  if (!(row >= 1)) return -1;
+  const idx = firstVisibleRow(owners.length, height, offset) + (row - 1);
+  return idx < 0 || idx >= owners.length ? -1 : owners[idx];
+}
+
+/**
+ * The 1-based viewport rows currently showing recorded lines `from..to`, in order.
+ *
+ * The inverse of lineAtViewportRow, and it must stay that way — it is what lets a change that
+ * only RECOLOURS a block repaint the block's own rows instead of the whole view. Rows scrolled
+ * off the top, and rows below the transcript, are simply absent.
+ */
+export function viewportRowsForLines(owners, from, to, height) {
+  const first = firstVisibleRow(owners.length, height);
+  const out = [];
+  for (let i = first; i < owners.length; i++) {
+    if (owners[i] < from || owners[i] > to) continue;
+    const row = i - first + 1;
+    if (row >= 1 && row <= Math.max(1, height)) out.push({ row, index: i });
+  }
+  return out;
+}
+
+/**
+ * The slice of `lines` to show, given how far back the user has scrolled.
+ *
+ * `offset` counts lines from the BOTTOM: 0 is live (the newest `height` lines). It is clamped
+ * here rather than by the caller, so a wheel spun past the top or bottom simply stops — the
+ * caller can always add its delta blindly and ask what actually happened.
+ */
+export function viewportSlice(lines, offset, height) {
+  const h = Math.max(1, height);
+  const maxOffset = Math.max(0, lines.length - h);
+  const clamped = Math.max(0, Math.min(offset, maxOffset));
+  const end = lines.length - clamped;
+  const rows = lines.slice(Math.max(0, end - h), end);
+  return {
+    rows,
+    offset: clamped,
+    atBottom: clamped === 0,
+    /** Lines hidden BELOW the viewport — what "jump to bottom" would bring back. */
+    below: clamped,
+  };
+}
+
+/**
+ * Bytes that repaint the scrolling area (rows 1..height) with `rows`, top-aligned, each row
+ * cleared first and clipped so nothing wraps into the next one — a wrapped row here would push
+ * the whole view down by one and desynchronise every later repaint.
+ *
+ * The caret is left on the LAST painted row: while the user is scrolled back nothing types
+ * there, and parking it inside the region keeps the terminal from scrolling on its own.
+ *
+ * `preserveCaret:false` is what a caller that keeps its OUTPUT POSITION in the terminal's DECSC
+ * slot must pass — there is only one such slot, so bracketing this repaint with DECSC/DECRC
+ * overwrites the output position with wherever the caret happened to be (the input line), and
+ * the next printed line lands in the frozen zone, indented by the width of the prompt. Same
+ * hazard, same flag as `paintFrozenRowsSeq`.
+ */
+export function paintViewportSeq(rows, height, width, clip, { preserveCaret = true } = {}) {
+  const h = Math.max(1, height);
+  let out = preserveCaret ? "\x1b7" : "";
+  for (let i = 0; i < h; i++) {
+    const row = rows[i] ?? "";
+    out += `\x1b[${i + 1};1H\x1b[2K` + clip(row, Math.max(1, width - 1));
+  }
+  return out + (preserveCaret ? "\x1b8" : "");
+}
+
+/**
+ * The bar's top row while the user is scrolled back: it replaces the plain rule with the
+ * affordance that tells them where they are AND that a click brings them back. Returned as
+ * plain text plus the click target, so the caller styles it and hit-tests the row itself.
+ */
+export function jumpToBottomRow({ below, width }) {
+  const label = `↓ jump to bottom (click)  ·  ${below} line${below === 1 ? "" : "s"} below`;
+  const w = Math.max(20, width);
+  const pad = Math.max(0, Math.floor((w - label.length) / 2));
+  return { text: " ".repeat(pad) + label, from: pad, to: pad + label.length };
+}
+
+// ---------------------------------------------------------------------------------------
+// SELECTION (task #176) — turning a drag on the screen back into text.
+//
+// The terminal cannot help here. While gu reports mouse motion (?1003h), the terminal does
+// NOT run its own drag-select, and no escape sequence reports what a terminal has selected. So
+// a selection has to be tracked and extracted by us. That is also why this is worth doing at
+// all: macOS Terminal.app has no copy-on-select setting and never has, so "select and it is
+// copied" cannot be delegated to the emulator for half the users.
+//
+// Everything below is PURE — screen coordinates plus the recorded lines in, text out — so the
+// arithmetic can be argued with in a test instead of by dragging a mouse.
+// ---------------------------------------------------------------------------------------
+
+/** Colour escapes occupy no cells; selection maths is over VISIBLE characters only. */
+const _plain = (s) => String(s ?? "").replace(/\x1b\[[0-9;?]*[A-Za-z]/g, "");
+
+/**
+ * The two ends of a drag, in the order the text reads.
+ *
+ * A drag upward or right-to-left produces an anchor AFTER the focus, and every consumer would
+ * otherwise have to re-check. Ordered once, here.
+ */
+export function orderSelection(a, b) {
+  const A = { row: Math.max(0, a?.row | 0), col: Math.max(0, a?.col | 0) };
+  const B = { row: Math.max(0, b?.row | 0), col: Math.max(0, b?.col | 0) };
+  const backwards = B.row < A.row || (B.row === A.row && B.col < A.col);
+  return backwards ? { start: B, end: A } : { start: A, end: B };
+}
+
+/** Nothing was dragged — the two ends are the same cell. A plain click, not a selection. */
+export function isEmptySelection(sel) {
+  if (!sel?.start || !sel?.end) return true;
+  return sel.start.row === sel.end.row && sel.start.col === sel.end.col;
+}
+
+/**
+ * The text inside a selection, given the recorded lines and the width they are shown at.
+ *
+ * `start`/`end` are DISPLAY rows — what the user dragged over — and columns are visible cells.
+ * Two things make the result text rather than a screenshot:
+ *
+ *  · SOFT WRAP IS UNDONE. wrapVisible breaks a long line at the width with no word logic, so
+ *    display rows belonging to one recorded line rejoin with nothing between them and the
+ *    sentence is whole again. Rows from DIFFERENT recorded lines join with a newline.
+ *  · THE GUTTER IS DROPPED. Every line in this UI is indented into a shared text column; that
+ *    indent is layout, not content, and pasting it back into an editor reindents the world.
+ *
+ * What it deliberately does NOT do is undo a HARD wrap: renderAnswer emits each wrapped row as
+ * its own recorded line, so selecting an answer yields those rows. Task #158 is the reason the
+ * caller should prefer a registered block's SOURCE text when the selection covers one —
+ * selectionCoversLines() answers that — because a copied answer has to still run.
+ */
+export function selectionText(lines, sel, width, { gutter = "" } = {}) {
+  const all = Array.isArray(lines) ? lines : [];
+  const w = Math.max(1, width | 0);
+  if (!sel?.start || !sel?.end || !all.length) return "";
+  const { start, end } = orderSelection(sel.start, sel.end);
+  const rows = displayRows(all, w);
+  const owners = displayRowOwners(all, w);
+  if (!rows.length) return "";
+  // A drag that BEGINS past the last row selected nothing — clamping both ends would instead
+  // return the final row's text, which was never under the pointer. A drag that begins in the
+  // content and runs off the bottom is different, and clamps normally below.
+  if (start.row >= rows.length) return "";
+  const first = Math.min(start.row, rows.length - 1);
+  const last = Math.min(end.row, rows.length - 1);
+  if (last < first) return "";
+
+  const out = [];
+  let curOwner = null;
+  for (let r = first; r <= last; r++) {
+    const text = _plain(rows[r]);
+    const from = r === first ? Math.min(start.col, text.length) : 0;
+    const to = r === last ? Math.min(end.col, text.length) : text.length;
+    const piece = to > from ? text.slice(from, to) : "";
+    if (owners[r] === curOwner) out[out.length - 1] += piece; // same recorded line: soft wrap
+    else {
+      out.push(piece);
+      curOwner = owners[r];
+    }
+  }
+  const g = String(gutter || "");
+  return out
+    .map((l) => (g && l.startsWith(g) ? l.slice(g.length) : l))
+    .join("\n")
+    .replace(/[ \t]+$/gm, "");
+}
+
+/**
+ * A drag in SCREEN coordinates → the selection in ABSOLUTE display rows (task #176 → #219).
+ *
+ * The two spaces are different and the difference is the scroll position: screen rows are
+ * 1-based and count from the top of the viewport, absolute rows are 0-based and count from the
+ * top of the whole transcript. Everything downstream — the highlight painted by
+ * applySelectionHighlight, the text recovered by selectionText, the block lookup in
+ * selectionCoversLines — works in absolute rows, so this conversion is the single place the
+ * scroll position enters the selection at all. Getting it wrong does not fail loudly: it
+ * selects real text from the wrong part of the transcript.
+ *
+ * Lives here, pure, rather than in the REPL, because the REPL runs main() on import and so
+ * cannot be imported by a test — which is exactly how it went wrong. The version in the REPL
+ * open-coded `total - height`, could not see `offset`, and was therefore correct only at the
+ * live tail; the response had been to switch the whole feature off while scrolled back rather
+ * than to pass the offset in.
+ *
+ * THE COLUMN -1 BELONGS TO THE EARLIER END. It turns a 1-based mouse column into an inclusive
+ * 0-based one, and "earlier" means earlier ON SCREEN, not the anchor — which is the LATER end
+ * whenever the pointer was dragged right-to-left. Applying it to the anchor dropped a
+ * character off each end of every backwards drag, so the ordering has to happen first.
+ */
+export function absoluteSelection(sel, { total, height, offset = 0 } = {}) {
+  if (!sel?.start || !sel?.end) return null;
+  const firstVisible = firstVisibleRow(total | 0, height, offset);
+  const { start, end } = orderSelection(sel.start, sel.end);
+  return {
+    start: { row: firstVisible + (start.row - 1), col: Math.max(0, start.col - 1) },
+    end: { row: firstVisible + (end.row - 1), col: end.col },
+  };
+}
+
+/**
+ * Does this selection cover every display row of these recorded lines?
+ *
+ * The caller uses it to hand back a registered block's SOURCE instead of the painted rows
+ * (#158). Partial selections deliberately do not qualify: half a block cannot be mapped back
+ * into half a source string, and guessing would paste something that was never on screen.
+ */
+export function selectionCoversLines(sel, { fromLine, toLine, lines, width }) {
+  if (!sel?.start || !sel?.end) return false;
+  const owners = displayRowOwners(Array.isArray(lines) ? lines : [], Math.max(1, width | 0));
+  const { start, end } = orderSelection(sel.start, sel.end);
+  let firstRow = -1;
+  let lastRow = -1;
+  owners.forEach((owner, row) => {
+    if (owner >= fromLine && owner <= toLine) {
+      if (firstRow < 0) firstRow = row;
+      lastRow = row;
+    }
+  });
+  if (firstRow < 0) return false;
+  return start.row <= firstRow && end.row >= lastRow;
+}
+
+// A "word" for double-click: a run of characters a programmer would expect to travel together.
+// Deliberately WIDER than \w — a path, a dotted call and a kebab flag are each one thing to
+// someone double-clicking them, and splitting "src/api/graph.js" into five selections is the
+// behaviour that makes people stop using the feature.
+const _WORD_CHAR = /[A-Za-z0-9_\-./@:+~$]/;
+
+/**
+ * The word around a column, as {from, to} — or null when the column is not on one.
+ *
+ * Clicking whitespace selects nothing rather than the nearest word: guessing which side the
+ * user meant is wrong half the time, and an empty result is easy to retry.
+ */
+export function wordRangeAt(text, col) {
+  const s = _plain(text);
+  const i = Math.max(0, Math.min(col | 0, s.length - 1));
+  if (!s.length || !_WORD_CHAR.test(s[i] ?? "")) return null;
+  let from = i;
+  let to = i + 1;
+  while (from > 0 && _WORD_CHAR.test(s[from - 1])) from--;
+  while (to < s.length && _WORD_CHAR.test(s[to])) to++;
+  return { from, to };
+}
+
+/**
+ * Drag tracking, as a pure reducer (task #176).
+ *
+ * The three facts an SGR report carries — press, motion, release — arrive at different times and
+ * mean nothing individually; a selection is the shape they make together. Keeping that shape in
+ * a reducer means the rules can be argued with in a test, and the mouse handler is left doing
+ * only decode-and-dispatch.
+ *
+ * `state` is null (nothing in progress) or { anchor, focus, moved }. Returns { state, action }:
+ *
+ *   null              nothing to do
+ *   {type:"update"}   the selection changed and should be repainted
+ *   {type:"commit"}   the button came up on a real selection — copy it
+ *   {type:"cancel"}   the button came up without moving: a CLICK, not a selection — `at` is
+ *                     the cell it went down on, so the caller can run the click behaviours
+ *                     from the release rather than guessing at press time (task #177)
+ *
+ * The commit/cancel split is the whole safety of auto-copy. Copying on every release would
+ * overwrite the clipboard on every stray click with an empty string, which is destructive and
+ * not undoable. `moved` is what separates the two, and it is set by comparing cells rather than
+ * by a timer, so a slow careful drag is still a drag.
+ */
+export function dragReduce(state, ev) {
+  const at = { row: Math.max(0, ev?.row | 0), col: Math.max(0, ev?.col | 0) };
+  switch (ev?.kind) {
+    case "press":
+      // A fresh press always restarts. A press arriving mid-drag means the previous release was
+      // never delivered (a lost focus, another window) — the old anchor is stale either way.
+      return { state: { anchor: at, focus: at, moved: false }, action: null };
+    case "motion": {
+      if (!state) return { state, action: null }; // hover, not a drag — the caller owns that
+      const moved = state.moved || at.row !== state.anchor.row || at.col !== state.anchor.col;
+      const next = { anchor: state.anchor, focus: at, moved };
+      return {
+        state: next,
+        action: moved ? { type: "update", sel: { start: next.anchor, end: next.focus } } : null,
+      };
+    }
+    case "release": {
+      if (!state) return { state: null, action: null };
+      const sel = { start: state.anchor, end: state.moved ? at : state.focus };
+      const moved = state.moved || at.row !== state.anchor.row || at.col !== state.anchor.col;
+      return {
+        state: null,
+        // `at` is where the button went DOWN, which is the cell a click is aimed at — the
+        // caller cannot recover it once the state is cleared, and the release cell is not the
+        // same thing (a click that slid within one cell still belongs to its anchor).
+        action: moved ? { type: "commit", sel } : { type: "cancel", at: state.anchor },
+      };
+    }
+    default:
+      return { state, action: null };
+  }
+}
+
+/**
+ * What an SGR button byte means for dragging: "press" | "motion" | "wheel" | null.
+ *
+ * Bit 5 (32) is motion, bit 6 (64) is the wheel, and the low two bits name the button — 0 being
+ * left. Anything else (right, middle, a modifier-only report) is not ours, and saying so here
+ * keeps the reducer from having to know about terminal encodings at all.
+ */
+export function dragEventKind(btn, press) {
+  const b = Number(btn) | 0;
+  if (b & 64) return "wheel";
+  if (press === "m") return "release";
+  if (b & 32) return (b & 0b11) === 0 ? "motion" : null; // motion with the LEFT button held
+  return (b & 0b11) === 0 ? "press" : null;
+}
+
+// The selection's colours (task #178). THE LOGO'S CYAN, as a BACKGROUND — not as text.
+//
+// 46 is the background of `\x1b[36m`, the exact colour the startup chevron is drawn in, so the
+// selection is the product's own colour rather than a fourth one invented for it. It is the
+// user's palette cyan, which means it still inherits their theme — unlike a 256-colour or
+// truecolor background, which would fight every custom scheme and every light terminal, the
+// same argument that kept syntax colour out of the edit cards.
+//
+// A BACKGROUND, because the cyan FOREGROUND is already spoken for: the ">> " prompt, where it
+// means "this is the line you are typing", and the jump-to-bottom hint. A foreground also
+// REPLACES the text's own — dragging across a red ✗ would recolour it, so the one signal #41
+// reserves for "you must not miss this" would be erased by looking at it. A background leaves
+// every foreground meaning intact and reads as a REGION, which is what a selection is.
+//
+// The explicit 30 (black) is not decoration: the prompt and the jump hint are CYAN TEXT, and
+// cyan on cyan is invisible. Flattening the foreground inside the selection costs colour
+// meaning for as long as the selection lasts, and is the price of legibility. Reverse video
+// (\x1b[7m) avoids it by letting the terminal swap whatever is there; a named colour was chosen
+// deliberately over it, so the selection looks like gu rather than like the terminal.
+export const SELECTION_SGR = "\x1b[46;30m";
+
+/**
+ * One row with the visible columns [from, to) highlighted.
+ *
+ * THE NESTING TRAP, which is why this walks the row instead of slicing it: the row already
+ * carries SGR runs, and every one of them ends in `\x1b[0m`. Wrapping a span in our background
+ * and letting an inner reset through would terminate the highlight at the first coloured token
+ * and silently lose it for the rest of the span — the same failure recorded against colourising
+ * the edit cards. So escapes inside the span are DROPPED, and the colour state that was active
+ * is re-opened after it.
+ *
+ * Adds only zero-width escapes, so visibleLen is unchanged and the row still occupies exactly
+ * one physical row (#109/#138).
+ */
+export function highlightRow(line, from, to, sgr = SELECTION_SGR) {
+  const text = String(line ?? "");
+  const lo = Math.max(0, from | 0);
+  const hi = to === Infinity ? Infinity : Math.max(lo, to | 0);
+  if (hi <= lo) return text;
+  const chars = [...text];
+  let out = "";
+  let col = 0;
+  let state = ""; // SGR runs active here, to re-open after the highlight
+  let open = false;
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === "\x1b") {
+      const m = /^\x1b\[[0-9;]*m/.exec(chars.slice(i).join(""));
+      if (m) {
+        state = m[0] === "\x1b[0m" ? "" : state + m[0];
+        // Inside the highlight the escape is dropped — see THE NESTING TRAP above.
+        if (!(col >= lo && col < hi)) out += m[0];
+        i += [...m[0]].length - 1;
+        continue;
+      }
+    }
+    const inSpan = col >= lo && col < hi;
+    if (inSpan && !open) { out += sgr; open = true; }
+    if (!inSpan && open) { out += "\x1b[0m" + state; open = false; }
+    out += chars[i];
+    col += charWidth(chars[i]);
+  }
+  if (open) out += "\x1b[0m" + state;
+  return out;
+}
+
+/**
+ * Every display row with the selection painted on it.
+ *
+ * `sel` is in ABSOLUTE display-row coordinates — the same space displayRows produces — so the
+ * highlight stays on the text it was drawn over when the view scrolls, rather than on whatever
+ * has moved under that screen row.
+ */
+export function applySelectionHighlight(rows, sel, sgr = SELECTION_SGR) {
+  const all = Array.isArray(rows) ? rows : [];
+  if (!sel?.start || !sel?.end || isEmptySelection(sel)) return all;
+  const { start, end } = orderSelection(sel.start, sel.end);
+  if (end.row < 0 || start.row >= all.length) return all;
+  return all.map((row, i) => {
+    if (i < start.row || i > end.row) return row;
+    const from = i === start.row ? start.col : 0;
+    const to = i === end.row ? end.col : Infinity;
+    return highlightRow(row, from, to, sgr);
+  });
+}