Add Binary Paste Mode (DEC mode 2033) for image/binary clipboard paste by christianparpart · Pull Request #1898 · contour-terminal/contour

christianparpart · 2026-02-23T00:39:48Z

protocol extension

Introduces DEC private mode 2033 that lets terminal applications receive binary clipboard data (e.g., images) via DCS sequences with MIME type metadata and base64 encoding. Feature detection uses DECRQM (CSI ? 2033 $ p), which cleanly distinguishes "supported but disabled" (Ps=2) from "not recognized" (Ps=0).

notes

I explicitly decided against chunking, for simplicity
obviously, one could use this also for sending clear text with mime text/plain. This is not prohibited. Then it's text with a mime type, whereas paste / bracketed paste can only be used for clear text, binary paste can send any data (text as well as binary).

checklist

consider extending it to allow the client app to request the accepted mime types

Copilot

Pull request overview

This PR introduces Binary Paste Mode (DEC mode 2033), a terminal protocol extension that enables terminal applications to receive binary clipboard data (such as images) via DCS sequences with MIME type metadata and base64 encoding. The implementation includes feature detection via DECRQM, allowing applications to distinguish between "supported but disabled" and "not recognized" states.

Changes:

Added DEC private mode 2033 with DCS-based sub-command architecture for binary data delivery ('d') and MIME preference configuration ('c')
Extended sequence parameter type from uint16_t to uint32_t to support larger binary payload sizes
Implemented clipboard handling with size limits (10 MB hard limit, 5 MB soft limit requiring user permission) and MIME type priority matching

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/vtbackend/primitives.h	Added BinaryPaste DECMode enum (2033) with conversion functions
src/vtbackend/Sequence.h	Changed parameter storage from uint16_t to uint32_t to support larger values
src/vtbackend/Terminal.h	Added API for binary paste mode, MIME preferences, and default MIME types
src/vtbackend/Terminal.cpp	Implemented mode handlers, preference management, and reset behavior
src/vtbackend/InputGenerator.h/cpp	Added generateBinaryPaste for DCS sequence generation with base64 encoding
src/vtbackend/Screen.h/cpp	Added hookBinaryPaste for parsing incoming MIME preference configuration
src/vtbackend/Functions.h	Defined BINARYPASTE DCS function with sub-command architecture
src/contour/TerminalSession.h/cpp	Integrated clipboard MIME type detection, size validation, and permission handling
src/vtbackend/BinaryPaste_test.cpp	Comprehensive test suite covering mode control, data delivery, and MIME configuration
docs/vt-extensions/binary-paste.md	Complete protocol specification with examples and adoption state tracking
examples/watch-clipboard-paste.cpp	Reference implementation demonstrating binary paste mode usage
CMakeLists.txt, mkdocs.yml, metainfo.xml	Build configuration, documentation index, and release notes

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/vtbackend/Screen.cpp

src/vtbackend/Terminal.cpp

src/vtbackend/Functions.h

src/vtbackend/Terminal.cpp

Introduce a new VT protocol extension that allows terminal applications to receive binary clipboard data (e.g., images) with MIME type metadata via DCS sequences. Applications opt in via DECSET 2033; feature detection uses DECRQM (CSI ? 2033 $ p) to distinguish "supported but disabled" from "not supported". Protocol: DCS 2033 ; <size> b <mime-type> ; <base64-data> ST - DECMode 2033: opt-in mode with standard DECSET/DECRST/DECRQM support - InputGenerator::generateBinaryPaste() produces DCS binary paste sequences - Terminal::sendBinaryPaste() routes binary data through the input pipeline - TerminalSession::pasteFromClipboard() inspects clipboard MIME types when mode is enabled, with priority: png > jpeg > gif > bmp > svg+xml - Size limits: 10 MB hard, 5 MB soft (user permission prompt) - Size validation: decoded payload must match declared Ps parameter - VT sequence parameters widened from uint16_t to uint32_t to support payload sizes beyond 64 KB (max ~4 GB) - 7 E2E tests covering mode control, DECRQM, DCS generation, and reset - VT extension spec at docs/vt-extensions/binary-paste.md with adoption table - Example app: examples/watch-clipboard-paste.cpp Signed-off-by: Christian Parpart <christian@parpart.family>

Yaraslaut

Some small comments, otherwise great addition

Yaraslaut · 2026-02-26T07:32:08Z

docs/vt-extensions/binary-paste.md

should we put it inside https://github.com/contour-terminal/vt-extensions/ as well ?

Yeah absolutely

Yaraslaut · 2026-02-26T08:11:37Z

src/contour/TerminalSession.cpp

+            if (!appPrefs.empty())
+                for (auto const& mime: appPrefs)
+                    mimeTypesToTry.emplace_back(mime);
+            else
+                for (auto const& mime: vtbackend::Terminal::DefaultBinaryPasteMimeTypes)
+                    mimeTypesToTry.emplace_back(mime);


please add brackets for every scope you add

Yaraslaut · 2026-02-26T08:12:23Z

src/contour/TerminalSession.cpp

+                auto const data = md->data(qMime);
+
+                // 10 MB hard limit for binary paste
+                if (data.size() > 10 * 1024 * 1024)


have it as constexpr variable

Yaraslaut · 2026-02-26T08:17:17Z

src/contour/TerminalSession.cpp

+                }
+
+                // 5 MB soft limit: request user permission
+                if (data.size() > 5 * 1024 * 1024)


also constexpr variable

Yaraslaut · 2026-02-26T08:18:10Z

src/contour/TerminalSession.cpp

+                }
+
+                auto const dataSpan = std::span<uint8_t const>(
+                    reinterpret_cast<uint8_t const*>(data.constData()), static_cast<size_t>(data.size()));


hm, i am slightly confused about the static cast for the size function, do we need it?

github-actions bot added documentation Improvements or additions to documentation VT: Backend Virtual Terminal Backend (libterminal API) frontend Contour Terminal Emulator (GUI frontend) test Unit tests labels Feb 23, 2026

christianparpart force-pushed the feature/binary-paste branch from 126192b to b66871e Compare February 23, 2026 00:45

github-actions bot added the CI GitHub Actions & CI label Feb 23, 2026

christianparpart force-pushed the feature/binary-paste branch from b66871e to e3af2c0 Compare February 23, 2026 00:47

christianparpart marked this pull request as draft February 23, 2026 01:34

christianparpart force-pushed the feature/binary-paste branch 2 times, most recently from 42f5493 to 675f366 Compare February 23, 2026 08:54

christianparpart marked this pull request as ready for review February 23, 2026 09:07

christianparpart requested review from Yaraslaut and Copilot February 23, 2026 09:11

Copilot started reviewing on behalf of christianparpart February 23, 2026 09:11 View session

christianparpart force-pushed the feature/binary-paste branch from 675f366 to 3cb4f63 Compare February 23, 2026 09:23

Copilot AI reviewed Feb 23, 2026

View reviewed changes

src/vtbackend/Screen.cpp Outdated Show resolved Hide resolved

src/vtbackend/Terminal.cpp Show resolved Hide resolved

src/vtbackend/Functions.h Outdated Show resolved Hide resolved

src/vtbackend/Terminal.cpp Show resolved Hide resolved

christianparpart force-pushed the feature/binary-paste branch from 3cb4f63 to aa1cd42 Compare February 23, 2026 09:45

christianparpart force-pushed the feature/binary-paste branch from aa1cd42 to 7935b92 Compare February 23, 2026 15:11

christianparpart self-assigned this Feb 26, 2026

Yaraslaut approved these changes Feb 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add Binary Paste Mode (DEC mode 2033) for image/binary clipboard paste#1898

Add Binary Paste Mode (DEC mode 2033) for image/binary clipboard paste#1898
christianparpart wants to merge 1 commit intomasterfrom
feature/binary-paste

christianparpart commented Feb 23, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Yaraslaut left a comment

Uh oh!

Yaraslaut Feb 26, 2026

Uh oh!

christianparpart Feb 26, 2026

Uh oh!

Yaraslaut Feb 26, 2026

Uh oh!

Yaraslaut Feb 26, 2026

Uh oh!

Yaraslaut Feb 26, 2026

Uh oh!

Yaraslaut Feb 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

christianparpart commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

protocol extension

notes

checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Yaraslaut left a comment

Choose a reason for hiding this comment

Uh oh!

Yaraslaut Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

christianparpart Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Yaraslaut Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Yaraslaut Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Yaraslaut Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Yaraslaut Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

christianparpart commented Feb 23, 2026 •

edited

Loading