From 2c233a5c04f12ada58e3908c376c5e28bfdb38ef Mon Sep 17 00:00:00 2001
From: Ramiz Wachtler <ramiz@earendil.com>
Date: Wed, 5 Aug 2026 09:50:58 +0200
Subject: [PATCH] fix(tui): add iterm payload size for xterm.js image addon
 (#7612)

- include decoded byte count in iterm2 osc 1337 sequences
- satisfy @xterm/addon-image@0.9.0 image validation
- fixes #7465
---
 packages/tui/src/terminal-image.ts       | 5 ++++-
 packages/tui/test/terminal-image.test.ts | 8 ++++++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/packages/tui/src/terminal-image.ts b/packages/tui/src/terminal-image.ts
index 1fa555829..cef4e4405 100644
--- a/packages/tui/src/terminal-image.ts
+++ b/packages/tui/src/terminal-image.ts
@@ -250,7 +250,10 @@ export function encodeITerm2(
 		inline?: boolean;
 	} = {},
 ): string {
-	const params: string[] = [`inline=${options.inline !== false ? 1 : 0}`];
+	const params: string[] = [
+		`inline=${options.inline !== false ? 1 : 0}`,
+		`size=${Buffer.byteLength(base64Data, "base64")}`,
+	];
 
 	if (options.width !== undefined) params.push(`width=${options.width}`);
 	if (options.height !== undefined) params.push(`height=${options.height}`);
diff --git a/packages/tui/test/terminal-image.test.ts b/packages/tui/test/terminal-image.test.ts
index 34f2bb74d..ec52878be 100644
--- a/packages/tui/test/terminal-image.test.ts
+++ b/packages/tui/test/terminal-image.test.ts
@@ -13,6 +13,7 @@ import {
 	deleteAllKittyPlacements,
 	deleteKittyImage,
 	detectCapabilities,
+	encodeITerm2,
 	encodeKitty,
 	getKittyImageMetadata,
 	getKittyImagePlacement,
@@ -375,6 +376,13 @@ describe("detectCapabilities", () => {
 	});
 });
 
+describe("iTerm2 image encoding", () => {
+	it("includes the decoded payload size in OSC 1337 metadata", () => {
+		const sequence = encodeITerm2("AAAA", { width: 2, height: "auto" });
+		assert.strictEqual(sequence, "\x1b]1337;File=inline=1;size=3;width=2;height=auto:AAAA\x07");
+	});
+});
+
 describe("Kitty image cursor movement", () => {
 	it("can request no terminal-side cursor movement", () => {
 		const sequence = encodeKitty("AAAA", { columns: 2, rows: 2, moveCursor: false });