feat(🎄🎁): support reading the OSC52 clipboard contents in tests (#862)

**Issue:**

An important part of terminal applications is the ability to set and
read the system clipboard. This is not possible to test.

**Solution:**

Support an in-memory OSC52 clipboard in the terminal testing session
that can be tested. OSC52 is a terminal escape sequence that allows
terminal applications to set the clipboard contents of the host
terminal. It works locally and even over ssh connections.

Features:

- store the latest clipboard contents in memory, and allow **read-only**
  access in tests.
  - tests can only read the clipboard contents, not set them.
  - the test application (e.g. neovim) can read + write the clipboard
    contents normally using OSC52 requests.
  - Does not affect the system clipboard of the host system (your
    computer), which could disturb other tasks while the tests are
    running. Now they are completely separate.
- support both "system" and "primary" clipboards. This is what xtermjs
  exposes, and we now support both. The "system" clipboard seems to be
  the default on macOS, while "primary" is probably used on Linux X11.

References:

- xtermjs 6.0 added support for OSC52 clipboard requests via
  xtermjs/xterm.js#4220
- https://neovim.io/doc/user/provider.html#clipboard-osc52

Closes #857

Author: mikavilpas

packages/integration-tests/cypress/e2e/neovim.cy.ts

@@ -406,6 +406,42 @@ describe("nvim_isRunning", () => {
     })
   })
 
+  it("can read the OSC52 clipboard contents", () => {
+    // OSC52 allows terminal applications to set the system clipboard by sending
+    // an escape sequence. Neovim supports this natively since version 0.10.
+    //
+    // References:
+    // - https://github.com/neovim/neovim/pull/25872
+    // - :help clipboard-osc52 (https://neovim.io/doc/user/provider.html#clipboard-osc52)
+    cy.visit("/")
+    cy.startNeovim().then(nvim => {
+      cy.contains("If you see this text, Neovim is ready!")
+
+      // Verify clipboard starts empty
+      nvim.clipboard.system().should("eql", "")
+
+      // Configure Neovim to use OSC52 for clipboard
+      //
+      // See `:help clipboard-osc52` in neovim for more information
+      nvim.runLuaCode({ luaCode: `vim.g.clipboard = 'osc52'` })
+
+      // Yank some text to the clipboard using Neovim
+      // First, select the word "see" and yank it to the + register
+      cy.typeIntoTerminal("/see{enter}")
+      cy.typeIntoTerminal('viw"+y')
+
+      // Verify the clipboard now contains "see"
+      nvim.clipboard.system().should("eql", "see")
+
+      // verify that the clipboard contents can be read
+      cy.typeIntoTerminal(`"_dd`)
+      cy.typeIntoTerminal("p")
+      nvim.waitForLuaCode({
+        luaAssertion: `assert(vim.api.nvim_buf_get_lines(0, 0, -1, false)[1] == 'see')`,
+      })
+    })
+  })
+
   // test some types and make sure they are as expected
 
   // oxlint-disable-next-line no-constant-condition

packages/integration-tests/cypress/e2e/terminal.cy.ts

@@ -135,6 +135,29 @@ describe("TerminalTestApplication features", () => {
     })
   })
 
+  it("can support OSC52 clipboard requests", () => {
+    // OSC52 is used this way: the terminal application sends an escape
+    // sequence that requests the host terminal (e.g. iTerm2, kitty, wezterm,
+    // ghostty) to set the clipboard contents to some data. This should work
+    // even through an ssh connection to an external system, so it's very
+    // flexible.
+    //
+    // Some references:
+    // - https://github.com/xtermjs/xterm.js/pull/4220
+    // - https://github.com/neovim/neovim/pull/25872
+    cy.visit("/")
+    cy.startTerminalApplication({
+      commandToRun: ["bash"],
+    }).then(term => {
+      cy.contains("myprompt")
+      term.clipboard.system().should("eql", "")
+
+      // send an OSC52 clipboard set request to the terminal
+      cy.typeIntoTerminal(`printf "\\033]52;c;$(printf "%s" "blabla" | base64)\\a"{enter}`)
+      term.clipboard.system().should("eql", "blabla")
+    })
+  })
+
   describe("mise integration", () => {
     it("can use applications installed to the host environment with the miseIntegration", () => {
       cy.visit("/")

packages/integration-tests/cypress/support/tui-sandbox.ts

@@ -36,6 +36,12 @@ export type TerminalTestApplicationContext = {
 
   /** The test directory, providing type-safe access to its file and directory structure */
   dir: TestDirectory<MyTestDirectory>
+
+  /** Access to the clipboard of the terminal */
+  clipboard: {
+    system(): Cypress.Chainable<string>
+    primary(): Cypress.Chainable<string>
+  }
 }
 
 /** The api that can be used in tests after a Neovim instance has been started. */
@@ -76,6 +82,12 @@ export type NeovimContext = {
 
   /** The test directory, providing type-safe access to its file and directory structure */
   dir: TestDirectory<MyTestDirectory>
+
+  /** Access to the clipboard of the terminal */
+  clipboard: {
+    system(): Cypress.Chainable<string>
+    primary(): Cypress.Chainable<string>
+  }
 }
 
 /** Arguments for starting the neovim server. They are built based on your test
@@ -127,6 +139,15 @@ Cypress.Commands.add("startNeovim", (startArguments?: MyStartNeovimServerArgumen
         cy.typeIntoTerminal(text, options)
       },
       dir: underlyingNeovim.dir as TestDirectory<MyTestDirectory>,
+
+      clipboard: {
+        primary() {
+          return cy.then(() => underlyingNeovim.clipboard.primary())
+        },
+        system() {
+          return cy.then(() => underlyingNeovim.clipboard.system())
+        },
+      },
     }
 
     return api
@@ -163,6 +184,14 @@ Cypress.Commands.add("startTerminalApplication", (args: StartTerminalGenericArgu
       typeIntoTerminal(text, options) {
         cy.typeIntoTerminal(text, options)
       },
+      clipboard: {
+        primary() {
+          return cy.then(() => terminal.clipboard.primary())
+        },
+        system() {
+          return cy.then(() => terminal.clipboard.system())
+        },
+      },
     }
 
     return api

packages/library/package.json

@@ -46,6 +46,7 @@
     "@catppuccin/palette": "1.7.1",
     "@trpc/client": "11.8.1",
     "@trpc/server": "11.8.1",
+    "@xterm/addon-clipboard": "0.2.0",
     "@xterm/addon-fit": "0.10.0",
     "@xterm/addon-unicode11": "0.8.0",
     "@xterm/xterm": "5.5.0",

packages/library/src/browser/neovim-client.ts

@@ -1,5 +1,6 @@
 import type { Terminal } from "@xterm/xterm"
 import "@xterm/xterm/css/xterm.css"
+import type { InMemoryClipboard } from "../client/clipboard.js"
 import { NeovimTerminalClient } from "../client/neovim-terminal-client.js"
 import type { TuiTerminalApi } from "../client/startTerminal.js"
 import "../client/style.css"
@@ -38,6 +39,7 @@ export type GenericNeovimBrowserApi = {
   waitForLuaCode(input: PollLuaCodeClientInput): Promise<RunLuaCodeOutput>
   runExCommand(input: ExCommandClientInput): Promise<RunExCommandOutput>
   dir: TestDirectory
+  clipboard: InMemoryClipboard
 }
 
 /** Entrypoint for the test runner (cypress) */
@@ -68,6 +70,7 @@ window.startNeovim = async function (startArgs?: StartNeovimGenericArguments): P
       return neovim.runExCommand(input)
     },
     dir: testDirectory,
+    clipboard: neovim.clipboard,
   }
 
   return neovimBrowserApi
@@ -83,6 +86,7 @@ declare global {
 export type GenericTerminalBrowserApi = {
   dir: TestDirectory
   runBlockingShellCommand(input: BlockingCommandClientInput): Promise<BlockingShellCommandOutput>
+  clipboard: InMemoryClipboard
 }
 
 export type BrowserTerminalSettings = {
@@ -123,6 +127,7 @@ window.startTerminalApplication = async function (
     runBlockingShellCommand(input) {
       return terminal.runBlockingShellCommand(input)
     },
+    clipboard: terminal.clipboard,
   }
   return terminalBrowserApi
 }

packages/library/src/client/clipboard.ts

@@ -0,0 +1,36 @@
+import type { ClipboardSelectionType, IClipboardProvider } from "@xterm/addon-clipboard"
+
+export type InMemoryClipboard = {
+  /**
+   * Get the system clipboard contents. This seems to be the default on osx. If
+   * you know what other systems use this by default, please open an issue or
+   * PR to enhance this documentation!
+   */
+  system(): string
+
+  /** Get the primary clipboard contents. */
+  primary(): string
+}
+
+export class InMemoryClipboardProvider implements IClipboardProvider, InMemoryClipboard {
+  private clipboardContents: Record<ClipboardSelectionType, string> = {
+    c: "", // SYSTEM
+    p: "", // PRIMARY
+  }
+
+  public system(): string {
+    return this.clipboardContents.c
+  }
+
+  public primary(): string {
+    return this.clipboardContents.p
+  }
+
+  async readText(selection: ClipboardSelectionType): Promise<string> {
+    return this.clipboardContents[selection]
+  }
+
+  async writeText(selection: ClipboardSelectionType, text: string): Promise<void> {
+    this.clipboardContents[selection] = text
+  }
+}

packages/library/src/client/index.ts

@@ -1,5 +1,6 @@
 // This is the public client api. Semantic versioning will be applied to this.
 
+export type { InMemoryClipboard } from "./clipboard.js"
 export { rgbify } from "./color-utilities.js"
 export { textIsVisibleWithBackgroundColor, textIsVisibleWithColor } from "./cypress-assertions.js"
 export type { MyNeovimConfigModification } from "./MyNeovimConfigModification.ts"

packages/library/src/client/neovim-terminal-client.ts

@@ -15,6 +15,8 @@ import type {
   StartNeovimGenericArguments,
   TestDirectory,
 } from "../server/types.js"
+import type { InMemoryClipboard } from "./clipboard.js"
+import { InMemoryClipboardProvider } from "./clipboard.js"
 import { getTabId, startTerminal } from "./startTerminal.js"
 
 /** Manages the terminal state in the browser as well as the (browser's)
@@ -24,6 +26,7 @@ export class NeovimTerminalClient {
   private readonly tabId: { tabId: string }
   private readonly terminal: Terminal
   private readonly trpc: ReturnType<typeof createTRPCClient<AppRouter>>
+  public readonly clipboard: InMemoryClipboard
 
   constructor(app: HTMLElement) {
     const trpc = createTRPCClient<AppRouter>({
@@ -44,6 +47,7 @@ export class NeovimTerminalClient {
     this.tabId = getTabId()
     const tabId = this.tabId
 
+    const clipboard = new InMemoryClipboardProvider()
     const terminal = startTerminal(app, {
       onMouseEvent(data: string) {
         void trpc.neovim.sendStdin.mutate({ tabId, data }).catch((error: unknown) => {
@@ -53,7 +57,9 @@ export class NeovimTerminalClient {
       onKeyPress(event) {
         void trpc.neovim.sendStdin.mutate({ tabId, data: event.key })
       },
+      clipboard,
     })
+    this.clipboard = clipboard
     this.terminal = terminal
 
     // start listening to Neovim stdout - this will take some (short) amount of

packages/library/src/client/startTerminal.ts

@@ -1,14 +1,17 @@
 import { flavors } from "@catppuccin/palette"
+import { ClipboardAddon } from "@xterm/addon-clipboard"
 import { FitAddon } from "@xterm/addon-fit"
 import { Unicode11Addon } from "@xterm/addon-unicode11"
 import { Terminal } from "@xterm/xterm"
 import * as z from "zod"
 import type { TabId } from "../server/utilities/tabId.ts"
+import type { InMemoryClipboardProvider } from "./clipboard.js"
 import { validateMouseEvent } from "./validateMouseEvent.js"
 
 export type TuiTerminalApi = {
   onMouseEvent: (data: string) => void
   onKeyPress: (event: { key: string; domEvent: KeyboardEvent }) => void
+  clipboard: InMemoryClipboardProvider
 }
 export function startTerminal(app: HTMLElement, api: TuiTerminalApi): Terminal {
   const terminal = new Terminal({
@@ -38,23 +41,28 @@ export function startTerminal(app: HTMLElement, api: TuiTerminalApi): Terminal {
     yellow: colors.yellow.hex,
   }
 
-  // The FitAddon makes the terminal fit the size of the container, the entire
-  // page in this case
-  const fitAddon = new FitAddon()
-  terminal.loadAddon(fitAddon)
+  {
+    // The FitAddon makes the terminal fit the size of the container, the entire
+    // page in this case
+    const fitAddon = new FitAddon()
+    terminal.loadAddon(fitAddon)
 
-  // The Unicode11Addon fixes emoji rendering issues. Without it, emoji are
-  // displayed as truncated (partial) images.
-  const unicode11Addon = new Unicode11Addon()
-  terminal.loadAddon(unicode11Addon)
-  terminal.unicode.activeVersion = "11"
+    // The Unicode11Addon fixes emoji rendering issues. Without it, emoji are
+    // displayed as truncated (partial) images.
+    const unicode11Addon = new Unicode11Addon()
+    terminal.loadAddon(unicode11Addon)
+    terminal.unicode.activeVersion = "11"
 
-  terminal.open(app)
-  fitAddon.fit()
-
-  window.addEventListener("resize", () => {
+    terminal.open(app)
     fitAddon.fit()
-  })
+
+    window.addEventListener("resize", () => {
+      fitAddon.fit()
+    })
+
+    const clipboardAddon = new ClipboardAddon(undefined, api.clipboard)
+    terminal.loadAddon(clipboardAddon)
+  }
 
   terminal.onData(data => {
     data satisfies string

packages/library/src/client/terminal-terminal-client.ts

@@ -4,6 +4,8 @@ import type { StartTerminalBrowserArguments } from "../browser/neovim-client.js"
 import type { BlockingCommandClientInput } from "../server/blockingCommandInputSchema.js"
 import type { AppRouter } from "../server/server.js"
 import type { BlockingShellCommandOutput, ServerTestDirectory } from "../server/types.js"
+import type { InMemoryClipboard } from "./clipboard.js"
+import { InMemoryClipboardProvider } from "./clipboard.js"
 import type { TuiTerminalApi } from "./startTerminal.js"
 import { getTabId, startTerminal } from "./startTerminal.js"
 import { supportDA1 } from "./terminal-config.js"
@@ -15,7 +17,9 @@ export class TerminalTerminalClient {
   private readonly tabId: { tabId: string }
   private readonly terminal: Terminal
   private readonly trpc: ReturnType<typeof createTRPCClient<AppRouter>>
-  terminalApi: TuiTerminalApi
+
+  public readonly clipboard: InMemoryClipboard
+  public readonly terminalApi: TuiTerminalApi
 
   constructor(app: HTMLElement) {
     const trpc = createTRPCClient<AppRouter>({
@@ -36,6 +40,7 @@ export class TerminalTerminalClient {
     this.tabId = getTabId()
     const tabId = this.tabId
 
+    const clipboard = new InMemoryClipboardProvider()
     this.terminalApi = {
       onMouseEvent(data: string) {
         void trpc.terminal.sendStdin.mutate({ tabId, data }).catch((error: unknown) => {
@@ -45,7 +50,9 @@ export class TerminalTerminalClient {
       onKeyPress(event) {
         void trpc.terminal.sendStdin.mutate({ tabId, data: event.key })
       },
+      clipboard,
     }
+    this.clipboard = clipboard
     const terminal = startTerminal(app, this.terminalApi)
     this.terminal = terminal