Name selection writes instead of inferring a selection's identity (#1323)

Author: nedtwigg

docs/specs/mouse-and-clipboard.md

@@ -72,9 +72,9 @@ Source of truth: `lib/src/lib/terminal-mouse-router.ts`.
 
 ### 3.4 Selection Follows Content
 
-A selection is anchored to the characters under it, not to screen coordinates: stored in absolute buffer rows (scrollback + viewport).
+**Must anchor selections to characters in absolute buffer rows** (scrollback + viewport).
 
-- **Pure scroll** — vertical translation with no character changes — carries the selection along; coordinate math only, no matching.
+- **Must follow vertical scrolling and older scrollback trims** using coordinate math, never matching. **Must cancel when selected rows are trimmed**, even if identical text replaces them.
 - **Must cancel a finalized selection on the next xterm render when its extracted selected text changes**; repaints elsewhere are irrelevant. **Never add a partial-match or content-tracking heuristic** (§9.1).
 - **Terminal resize** carries a finalized linewise selection Dormouse owns, in the normal buffer, through xterm's reflow (rationale). Its editor stays open in the same format and same-labeled scope, else As selected; per-break edits drop unless the width held.
   - **Must cancel if an edge's line was trimmed or its cells no longer read as the selected text** (rationale).
@@ -180,7 +180,7 @@ Every break is a mark that a click cycles keep → space → none; a scope or fo
 - **Never show while its Wall travels**, its pane hidden, or another pane zoomed over it.
 - **Never take focus**; only an actual scrollbar press keeps its default (rationale). Presses inside it count as inside its pane (`anchoredTarget`); its `mousedown` and `contextmenu` never reach the pane.
 - **Esc**, a click outside the editor, a content change or a resize it cannot follow (§3.4), a confirmed copy, or **any input the terminal receives** — typing, a paste, Pocket's input bar — dismisses it and cancels the selection. Source of truth: `writeUserInput` in `lib/src/lib/terminal-lifecycle.ts`, pinned by `lib/src/lib/terminal-lifecycle.selection.test.ts`.
-- **Must confirm only after a successful clipboard write, and only for the selection copied**; the selection then clears, however it moved meanwhile (rationale).
+- **Must confirm only after a successful clipboard write, and only for the selection copied**; the selection then clears, even if its edges moved or reflow ran while the write was pending (rationale).
 - **Must leave empty copies idle without writing.** **Must say a failed write failed**, keeping the selection for a retry.
 - **Must write through the adapter's native `writeClipboardText` where it has one, and never fall back from it** (rationale). **Pocket's adapter must have none**: its copies belong on the phone. Without one, the write takes the Clipboard API, and `execCommand('copy')` where that is missing or refuses (rationale).
 - **Must open the clipboard-failure report when a write fails every way it may take**, unless its caller opts out. **Its details never carry the copied text**; they go to the tracking issue the report links.

lib/src/lib/copy-editor.test.ts

@@ -175,6 +175,17 @@ describe('copySelection', () => {
     }
   });
 
+  it.each([true, false])('reports a pending copy after nudging the same selection (copied: %s)', async copied => {
+    let complete!: (result: boolean) => void;
+    vi.mocked(writeTextToClipboard).mockImplementation(() => new Promise(resolve => { complete = resolve; }));
+    select({ endRow: 2, endCol: 11 });
+    const pending = copySelection(ID);
+    nudgeCopyEdge(ID, 'end', 1);
+    complete(copied);
+    await pending;
+    expect(getMouseSelectionState(ID)).toMatchObject({ selection: { endCol: 16 }, copyOutcome: copied ? 'copied' : 'failed' });
+  });
+
   it('says a failed write failed, for that selection', async () => {
     vi.mocked(writeTextToClipboard).mockResolvedValue(false);
     select({});
@@ -209,13 +220,19 @@ describe('copySelection', () => {
   });
 
   it.each([true, false])('neither flashes nor fails a newer selection when an earlier copy finishes (copied: %s)', async (copied) => {
-    let complete!: (copied: boolean) => void;
-    vi.mocked(writeTextToClipboard).mockImplementation(() => new Promise((resolve) => { complete = resolve; }));
-    select({});
-    const pending = copySelection(ID);
-    beginDrag(ID, { row: 9, col: 1, altKey: false, startedInScrollback: false });
-    complete(copied);
-    await pending;
-    expect(getMouseSelectionState(ID)).toMatchObject({ copyOutcome: null, selection: { startRow: 9 } });
+    const newer = [
+      () => beginDrag(ID, { row: 9, col: 1, altKey: false, startedInScrollback: false }),
+      () => select({ startRow: 9, endRow: 9 }),
+    ];
+    for (const replace of newer) {
+      let complete!: (copied: boolean) => void;
+      vi.mocked(writeTextToClipboard).mockImplementation(() => new Promise((resolve) => { complete = resolve; }));
+      select({});
+      const pending = copySelection(ID);
+      replace();
+      complete(copied);
+      await pending;
+      expect(getMouseSelectionState(ID)).toMatchObject({ copyOutcome: null, selection: { startRow: 9 } });
+    }
   });
 });

lib/src/lib/copy-editor.ts

@@ -37,23 +37,23 @@ export function openCopyEditor(id: string, terminal: Terminal | undefined = regi
   if (terminal && sel && !sel.dragging) setCopyEditor(id, editorFor(terminalCopyBuffer(terminal), spanOfSelection(sel), 'auto'));
 }
 
-/** Move the selection to `span`, where a resize's reflow put its cells, and
- *  rebuild its editor from the terminal (spec §3.4). Writes nothing when
- *  neither the span nor the editor's width changed. */
+/** Move the selection to `span`, where a scroll, trim, or resize's reflow put
+ *  its cells, and rebuild its editor from the terminal (spec §3.4). Writes
+ *  nothing when neither the span nor the editor's width changed. */
 export function followCopySelection(id: string, terminal: Terminal, span: Span): void {
   const { selection, copyEditor: editor } = getMouseSelectionState(id);
   if (!selection) return;
   const sameWidth = editor?.buffer.cols === terminal.cols;
   if (spanEquals(span, spanOfSelection(selection)) && (!editor || sameWidth)) return;
   const moved = selectionOfSpan(span, selection);
   if (!editor) {
-    setSelection(id, moved);
+    setSelection(id, moved, null, 'follow');
     return;
   }
   const next = editorFor(terminalCopyBuffer(terminal), span, editor.format);
   const label = editor.scopes[editor.scope].label;
   const scope = next.scopes.findIndex((s) => s.label === label);
-  setSelection(id, moved, { ...next, scope: Math.max(0, scope), overrides: scope >= 0 && sameWidth ? editor.overrides : {} });
+  setSelection(id, moved, { ...next, scope: Math.max(0, scope), overrides: scope >= 0 && sameWidth ? editor.overrides : {} }, 'follow');
 }
 
 export type FormatRenderings = Partial<Record<EditorFormat, Rendering>>;
@@ -163,5 +163,5 @@ export function nudgeCopyEdge(id: string, edge: 'start' | 'end', dir: 1 | -1): v
     ? { ...span, start: nudge(buf, span.start, dir, 'start') }
     : { ...span, end: nudge(buf, span.end, dir, 'end') };
   if (spanEquals(moved, span) || comparePos(moved.start, moved.end) > 0) return;
-  setSelection(id, selectionOfSpan(moved, sel), editorFor(buf, moved, copyEditor.format));
+  setSelection(id, selectionOfSpan(moved, sel), editorFor(buf, moved, copyEditor.format), 'edit');
 }

lib/src/lib/copy-selection.ts

@@ -14,12 +14,12 @@ import { COPY_FLASH_MS, failCopy, flashCopy, getMouseSelectionState, TOUCH_COPY_
  * says so instead, for that selection, and keeps it.
  */
 export async function copySelection(terminalId: string, { touch = false }: { touch?: boolean } = {}): Promise<void> {
-  const { selection, copyEditor, programCopy } = getMouseSelectionState(terminalId);
+  const { selection, selectionEpoch, copyEditor, programCopy } = getMouseSelectionState(terminalId);
   if (!selection || !copyEditor) return;
   const text = editorRendering(copyEditor, programCopy).text;
   if (!text) return;
   const copied = await writeTextToClipboard(text);
-  if (getMouseSelectionState(terminalId).selection !== selection) return;
+  if (getMouseSelectionState(terminalId).selectionEpoch !== selectionEpoch) return;
   if (!copied) {
     failCopy(terminalId);
     return;

lib/src/lib/mouse-selection.test.ts

@@ -40,6 +40,7 @@ describe('mouse-selection: default state', () => {
       bracketedPaste: false,
       override: 'off',
       selection: null,
+      selectionEpoch: 0,
       hintToken: null,
       copyEditor: null,
       programCopy: null,

lib/src/lib/mouse-selection.ts

@@ -63,6 +63,9 @@ export interface MouseSelectionState {
   bracketedPaste: boolean;
   override: OverrideState;
   selection: Selection | null;
+  /** Bumped when a selection ends or is replaced; held through an edit or
+   *  follow ({@link SelectionWrite}). */
+  selectionEpoch: number;
   /** The token under a drag's head, in absolute buffer rows. */
   hintToken: BufferToken | null;
   /** Open while non-null: always the editor written with this exact
@@ -84,6 +87,7 @@ export const DEFAULT_MOUSE_SELECTION_STATE: MouseSelectionState = Object.freeze(
   bracketedPaste: false,
   override: 'off',
   selection: null,
+  selectionEpoch: 0,
   hintToken: null,
   copyEditor: null,
   programCopy: null,
@@ -98,6 +102,7 @@ let cachedSnapshot: Map<string, MouseSelectionState> | null = null;
  *  one cannot leave another's editor, offer, or flash behind. */
 function clearSelection(s: MouseSelectionState): void {
   s.selection = null;
+  s.selectionEpoch++;
   s.copyEditor = null;
   s.programCopy = null;
   s.copyOutcome = null;
@@ -170,22 +175,27 @@ export function setOverride(id: string, override: OverrideState): void {
   notify();
 }
 
+/** How a write relates to the selection before it: `replace` starts another,
+ *  `edit` moves its edges, and `follow` carries the same cells through a
+ *  scroll, trim, or reflow, so only it keeps the program's offer. */
+export type SelectionWrite = 'replace' | 'edit' | 'follow';
+
 /**
  * Replace the selection and, in the same write, the copy editor over it: none
  * unless one is given for a finalized selection, so an editor never outlives
  * the selection it was opened for.
  */
-export function setSelection(id: string, selection: Selection | null, copyEditor: CopyEditorState | null = null): void {
+export function setSelection(id: string, selection: Selection | null, copyEditor: CopyEditorState | null = null, write: SelectionWrite = 'replace'): void {
   const s = ensure(id);
   if (s.selection === null && selection === null) return;
   if (selection === null) clearSelection(s);
   else {
-    // A replaced selection keeps an in-flight flash and the drag's hint, but
-    // not the program's offer, so its editor cannot show that offer either.
+    // Every write keeps the flash and drag hint.
+    if (write === 'replace') s.selectionEpoch++;
     s.selection = selection;
-    s.programCopy = null;
+    if (write !== 'follow') s.programCopy = null;
     s.copyEditor = selection.dragging || !copyEditor ? null
-      : copyEditor.format === 'program' ? { ...copyEditor, format: 'auto', overrides: {} } : copyEditor;
+      : copyEditor.format === 'program' && s.programCopy === null ? { ...copyEditor, format: 'auto', overrides: {} } : copyEditor;
   }
   notify();
 }

lib/src/lib/selection-reflow.ts

@@ -67,6 +67,13 @@ function locateEdge(buffer: IBuffer, edge: EdgeAnchor): GridPos | null {
   }
 }
 
+/** A marker on absolute buffer row `row`; `registerMarker` counts from the
+ *  cursor's row. */
+export function markRow(terminal: Terminal, row: number): IMarker {
+  const buffer = terminal.buffer.active;
+  return terminal.registerMarker(row - (buffer.baseY + buffer.cursorY));
+}
+
 /** Anchor a finalized linewise selection Dormouse owns; null for anything a
  *  resize cancels. The alternate buffer never reflows, and its program
  *  redraws on resize. */
@@ -78,11 +85,7 @@ export function anchorSelection(terminal: Terminal, sel: Selection): ReflowAncho
   const start = lineOffset(buffer, from, 'start');
   const end = lineOffset(buffer, to, 'end');
   if (text === null || !start || !end) return null;
-  const mark = ({ first, offset }: { first: number; offset: number }): EdgeAnchor => ({
-    // `registerMarker` counts from the cursor's row.
-    marker: terminal.registerMarker(first - (buffer.baseY + buffer.cursorY)),
-    offset,
-  });
+  const mark = ({ first, offset }: { first: number; offset: number }): EdgeAnchor => ({ marker: markRow(terminal, first), offset });
   const anchor: Anchor = {
     start: mark(start),
     end: mark(end),

lib/src/lib/selection-watch.test.ts

@@ -1,8 +1,9 @@
 // @vitest-environment jsdom
 import { afterEach, describe, expect, it } from 'vitest';
 import { Terminal } from '@xterm/xterm';
+import { openCopyEditor, setCopyFormat } from './copy-editor';
 import { finalizedSelection } from './copy-text-fixtures';
-import { __resetMouseSelectionForTests, getMouseSelectionState, setSelection } from './mouse-selection';
+import { __resetMouseSelectionForTests, getMouseSelectionState, offerProgramCopy, setSelection } from './mouse-selection';
 import { watchSelection } from './selection-watch';
 
 /** Cancel-on-change, compared on each render (docs/specs/mouse-and-clipboard.md
@@ -37,9 +38,53 @@ describe('watchSelection', () => {
     watch.dispose();
   });
 
+  it.each([
+    ['linewise', {}],
+    ['block', { shape: 'block' }],
+    ['program', { owner: 'program' }],
+  ] as const)('carries a %s selection when older scrollback is trimmed', async (kind, over) => {
+    const id = 'trim-' + kind;
+    const terminal = new Terminal({ cols: 20, rows: 3, scrollback: 3, allowProposedApi: true });
+    live.push(terminal);
+    await write(terminal, 'old0\r\nold1\r\nkeep A\r\nkeep B\r\ntail0\r\ntail1');
+    const watch = watchSelection(id, terminal);
+    setSelection(id, finalizedSelection({ startRow: 2, endRow: 3, endCol: 5, ...over }));
+    openCopyEditor(id, terminal);
+    if (kind === 'program') {
+      offerProgramCopy(id, 'source text');
+      setCopyFormat(id, 'program');
+    }
+    const markers = terminal.markers.map((m) => m.id);
+    await write(terminal, '\r\ntail2');
+    watch.onRender();
+    expect(getMouseSelectionState(id).selection).toMatchObject({ startRow: 1, endRow: 2, endCol: 5 });
+    // Following the trim reuses the markers that moved with it.
+    expect(terminal.markers.map((m) => m.id)).toEqual(markers);
+    expect(getMouseSelectionState(id).copyEditor).not.toBeNull();
+    if (kind === 'program') {
+      expect(getMouseSelectionState(id)).toMatchObject({ programCopy: 'source text', copyEditor: { format: 'program' } });
+    }
+    await write(terminal, '\r\ntail3\r\ntail4');
+    watch.onRender();
+    expect(getMouseSelectionState(id).selection).toBeNull();
+    watch.dispose();
+  });
+
+  it('cancels trimmed selected rows even when their replacements have identical text', async () => {
+    const terminal = new Terminal({ cols: 20, rows: 3, scrollback: 1, allowProposedApi: true });
+    live.push(terminal);
+    await write(terminal, 'same\r\nsame\r\nsame\r\nsame');
+    const watch = watchSelection('trim-identical', terminal);
+    setSelection('trim-identical', finalizedSelection({ endCol: 3 }));
+    await write(terminal, '\r\nsame');
+    watch.onRender();
+    expect(getMouseSelectionState('trim-identical').selection).toBeNull();
+    watch.dispose();
+  });
+
   it('releases its anchor and stops watching once disposed', async () => {
     const { terminal, watch } = await watched('w-2');
-    expect(terminal.markers).toHaveLength(2);
+    expect(terminal.markers).toHaveLength(3);
     watch.dispose();
     expect(terminal.markers).toHaveLength(0);
     setSelection('w-2', finalizedSelection({ endCol: 2 }));

lib/src/lib/selection-watch.ts

@@ -1,7 +1,8 @@
-import type { Terminal } from '@xterm/xterm';
+import type { IMarker, Terminal } from '@xterm/xterm';
 import { followCopySelection } from './copy-editor';
+import { spanOfSelection } from './copy-text';
 import { getMouseSelectionState, setSelection, subscribeToMouseSelection, type Selection } from './mouse-selection';
-import { anchorSelection, followReflow, type ReflowAnchor } from './selection-reflow';
+import { anchorSelection, followReflow, markRow, type ReflowAnchor } from './selection-reflow';
 import { extractSelectionText } from './selection-text';
 
 // A pane's selection held to the characters under it
@@ -22,17 +23,35 @@ export function watchSelection(id: string, terminal: Terminal): SelectionWatch {
   let baseline: string | null = null;
   /** Its edges, carried through a resize's reflow. */
   let anchor: ReflowAnchor | null = null;
+  // A full normal buffer trims its oldest rows as output arrives. One marker
+  // on the earlier edge distinguishes translation from replacement text.
+  let scrollMarker: IMarker | null = null;
+  /** While {@link onRender} follows a trim: the text matched and every marker
+   *  moved with it, so its write needs no fresh readings. */
+  let following = false;
   const unsubscribe = subscribeToMouseSelection(() => {
     const sel = getMouseSelectionState(id).selection;
     if (sel === selection) return;
     selection = sel;
+    if (following) return;
     baseline = sel && !sel.dragging ? extractSelectionText(terminal, sel) : null;
     anchor?.dispose();
     anchor = sel && anchorSelection(terminal, sel);
+    scrollMarker?.dispose();
+    scrollMarker = sel && !sel.dragging && terminal.buffer.active.type === 'normal'
+      ? markRow(terminal, Math.min(sel.startRow, sel.endRow)) : null;
   });
   return {
     onRender() {
-      if (selection && baseline !== null && extractSelectionText(terminal, selection) !== baseline) setSelection(id, null);
+      if (!selection || baseline === null) return;
+      if (scrollMarker?.isDisposed) { setSelection(id, null); return; }
+      const shift = scrollMarker ? scrollMarker.line - Math.min(selection.startRow, selection.endRow) : 0;
+      const moved = shift ? { ...selection, startRow: selection.startRow + shift, endRow: selection.endRow + shift } : selection;
+      if (extractSelectionText(terminal, moved) !== baseline) setSelection(id, null);
+      else if (moved !== selection) {
+        following = true;
+        try { followCopySelection(id, terminal, spanOfSelection(moved)); } finally { following = false; }
+      }
     },
     onResize() {
       const span = anchor && followReflow(terminal, anchor);
@@ -42,6 +61,7 @@ export function watchSelection(id: string, terminal: Terminal): SelectionWatch {
     dispose() {
       unsubscribe();
       anchor?.dispose();
+      scrollMarker?.dispose();
     },
   };
 }