From 5141a91bbab1582ff3d865f1aa839ec6a8dd2ac8 Mon Sep 17 00:00:00 2001
From: meganrogge <merogge@microsoft.com>
Date: Tue, 28 Oct 2025 10:27:00 -0400
Subject: [PATCH] add range to IHTMLSerializeOptions

---
 addons/addon-serialize/src/SerializeAddon.test.ts | 15 +++++++++++++++
 addons/addon-serialize/src/SerializeAddon.ts      |  7 +++++++
 .../addon-serialize/typings/addon-serialize.d.ts  |  5 +++++
 3 files changed, 27 insertions(+)

diff --git a/addons/addon-serialize/src/SerializeAddon.test.ts b/addons/addon-serialize/src/SerializeAddon.test.ts
index 0252b201..aacf76ed 100644
--- a/addons/addon-serialize/src/SerializeAddon.test.ts
+++ b/addons/addon-serialize/src/SerializeAddon.test.ts
@@ -148,6 +148,21 @@ describe('SerializeAddon', () => {
       assert.equal((output.match(/<div><span>&lt;a>&amp;pi;<\/span><\/div>/g) || []).length, 1, output);
     });
 
+    it('serializes rows within a provided range', async () => {
+      await writeP(terminal, 'hello\r\nworld');
+
+      const output = serializeAddon.serializeAsHTML({
+        range: {
+          start: 0,
+          end: 0
+        }
+      });
+      const rowMatches = output.match(/<div><span>.*?<\/span><\/div>/g) || [];
+      assert.equal(rowMatches.length, 1, output);
+      assert.ok(rowMatches[0]?.includes('hello'));
+      assert.ok(!output.includes('world'));
+    });
+
     it('cells with bold styling', async () => {
       await writeP(terminal, ' ' + sgr('1') + 'terminal' + sgr('22') + ' ');
 
diff --git a/addons/addon-serialize/src/SerializeAddon.ts b/addons/addon-serialize/src/SerializeAddon.ts
index 6f1d5d43..b8c567fc 100644
--- a/addons/addon-serialize/src/SerializeAddon.ts
+++ b/addons/addon-serialize/src/SerializeAddon.ts
@@ -450,6 +450,13 @@ export class SerializeAddon implements ITerminalAddon , ISerializeApi {
     const buffer = terminal.buffer.active;
     const handler = new HTMLSerializeHandler(buffer, terminal, options);
     const onlySelection = options.onlySelection ?? false;
+    const range = options.range;
+    if (range) {
+        return handler.serialize({
+          start: { x: 0,             y: typeof range.start === 'number' ? range.start : range.start.line },
+          end:   { x: terminal.cols, y: typeof range.end   === 'number' ? range.end   : range.end.line   }
+        });
+      }
     if (!onlySelection) {
       const maxRows = buffer.length;
       const scrollback = options.scrollback;
diff --git a/addons/addon-serialize/typings/addon-serialize.d.ts b/addons/addon-serialize/typings/addon-serialize.d.ts
index 90b8b428..d8d5fe07 100644
--- a/addons/addon-serialize/typings/addon-serialize.d.ts
+++ b/addons/addon-serialize/typings/addon-serialize.d.ts
@@ -90,6 +90,11 @@ declare module '@xterm/addon-serialize' {
      * Whether to include the global background of the terminal. False by default.
      */
     includeGlobalBackground: boolean;
+
+     /**
+     * The row range to serialize. This is prioritized over {@link onlySelection}.
+     */
+    range?: ISerializeRange;
   }
 
   export interface ISerializeRange {