fix(paste): cancel the Ctrl+V keydown once the paste trap has the clipboard

Ctrl+V in Firefox still pasted the clipboard twice some of the time.
Right-click → Paste never did.

`_handleImagePaste()` focuses a hidden contenteditable trap, calls
`document.execCommand('paste')`, and reads the clipboard from the paste
event that lands on the trap. Firefox dispatches that event synchronously,
inside the `execCommand` call. It then delivers the key's own paste as a
separate task, about 10 ms later in Playwright's Firefox. The one-shot flag
from b87bc687 drops that second event, but only if it still reaches the
trap. The trap removes itself and refocuses the terminal on a
`setTimeout(0)` queued by the first event, and that timer races the second
paste. When the timer wins, the second paste lands on xterm's textarea,
xterm's own `handlePasteEvent` sends the clipboard again, and the flag
never sees it.

The trap now cancels the keydown when its paste listener has already run
by the time `execCommand` returns, so Firefox never issues the second
paste. Both callers pass the keydown as `target.keyEvent`: the main pane's
key handler in terminal-ui.js and a tile's in terminal-tile.js. Chromium
and WebKit refuse the command and dispatch nothing from it, so their
keydown is left alone, because its default action delivers their only
paste event.

Measured in Playwright's Firefox with the trap removed before the key's
paste arrived: the paste reached xterm's textarea and the text went in
twice. With the keydown cancelled, the key's paste never fired. End to end
on an isolated instance with a shell session, 20 Ctrl+V presses gave 20
pastes in both Firefox and Chromium.

test/image-paste-trap.test.ts gains a harness option in which
`execCommand` delivers the paste from inside the call, as Firefox does.
New cases cover the keydown being cancelled for the main pane and for a
tile, being left alone when `execCommand` delivers nothing, and a caller
that passes no keydown. The two cancel cases fail without this change.

test/terminal-tile-input.test.ts now expects the tile to pass its keydown
along with its terminal and session.

Docs: the Terminal paste section of docs/architecture-invariants.md and
the paste-trap entry in src/web/CLAUDE.md now describe the race and the
rule. The section's old claim that the key's default action alone always
reaches the trap is replaced, since in Firefox it can miss it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Michael GrundbergandClaude Opus 5.5 committed 2026-11-10 08:20:41 +01:00
1 parent f62c1f7e2f
commit 6c5d53ebfe
7 files changed
+126 -26

No files matched your search

+17 -1
View File
@@ -196,11 +196,13 @@ Object.assign(CodemanApp.prototype, {
// own. Images upload to THAT session. Plain text goes to that pane's session
// as a Codeman-built bracketed-paste frame: the terminal is only refocused
// and receives input(framed). onData delivers the frame; it is not written
// into the xterm buffer.
// into the xterm buffer. `target.keyEvent` is the Ctrl+V keydown itself,
// which the trap cancels when execCommand('paste') has already delivered.
_handleImagePaste(target = {}) {
const self = this;
const terminal = target.terminal || this.terminal;
const sessionId = target.sessionId || this.activeSessionId;
const keyEvent = target.keyEvent;
// Create a hidden contenteditable div to receive the paste
const trap = document.createElement('div');
@@ -267,6 +269,20 @@ Object.assign(CodemanApp.prototype, {
// Trigger the browser's native paste via execCommand
// (this fires the paste event on our focused trap element)
document.execCommand('paste');
// Firefox dispatches the execCommand paste synchronously, inside the call
// above, and then delivers the key's own paste as a SEPARATE task about
// 10 ms later. That second event races the setTimeout above that removes
// the trap and refocuses the terminal. When the timer wins, the second
// paste lands on xterm's textarea, xterm's own paste handler sends the
// clipboard again, and the one-shot flag never sees it. That race is why
// Ctrl+V still pasted twice only sometimes. Once execCommand has delivered
// a paste, cancel the keydown so the browser never issues its own.
// Chromium and WebKit refuse the command and dispatch nothing here, so
// they keep the default action, which delivers their only paste event.
if (pasteConsumed && keyEvent && typeof keyEvent.preventDefault === 'function') {
keyEvent.preventDefault();
}
},
/** What a pick or a paste may upload: 'image', 'video' for the camera roll's
+1 -1
View File
@@ -349,7 +349,7 @@
// input(framed), which onData delivers. Mirrors terminal-ui.js's own
// Ctrl+V gate; without it xterm's default only ever pasted text.
if ((ev.ctrlKey || ev.metaKey) && ev.key === 'v' && ev.type === 'keydown') {
global.app?._handleImagePaste?.({ terminal: this.terminal, sessionId: this.sessionId });
global.app?._handleImagePaste?.({ terminal: this.terminal, sessionId: this.sessionId, keyEvent: ev });
return false;
}
// Ctrl+Z (SIGTSTP/job-control suspend), as terminal-ui.js swallows it:
+3 -1
View File
@@ -924,7 +924,9 @@ Object.assign(CodemanApp.prototype, {
// Route through our paste trap which handles both images and text.
if ((ev.ctrlKey || ev.metaKey) && ev.key === 'v' && ev.type === 'keydown') {
if (this.activeSessionId && this._handleImagePaste) {
this._handleImagePaste();
// The trap cancels this keydown itself when execCommand('paste')
// already delivered the clipboard (Firefox), so pass the event in.
this._handleImagePaste({ keyEvent: ev });
}
return false;
}