From 8e1e0884eafa5b999558475ad1595779b51c346b Mon Sep 17 00:00:00 2001
From: nirupamzenith <sainirupamkakani@gmail.com>
Date: Fri, 7 Aug 2026 22:17:10 +0530
Subject: [PATCH 1/3] tty: add stub for async OSC 11 background color query

Signed-off-by: nirupamzenith <sainirupamkakani@gmail.com>
---
 doc/api/tty.md                           | 21 +++++++++++++++++++++
 lib/tty.js                               | 14 ++++++++++++++
 test/parallel/test-tty-osc11-bg-color.js | 18 ++++++++++++++++++
 3 files changed, 53 insertions(+)
 create mode 100644 test/parallel/test-tty-osc11-bg-color.js

diff --git a/doc/api/tty.md b/doc/api/tty.md
index 03f86cd66052..89c28adeb523 100644
--- a/doc/api/tty.md
+++ b/doc/api/tty.md
@@ -212,6 +212,27 @@ changes:
 `writeStream.cursorTo()` moves this `WriteStream`'s cursor to the specified
 position.
 
+
+### `writeStream.getBackgroundColor()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {Promise} Resolves with `{ r, g, b }` (0-255 each) representing the
+  terminal's background color, or `undefined` if the terminal does not
+  support or respond to the query in time.
+
+Queries the terminal for its background color using the OSC 11 escape
+sequence and resolves with the result.
+
+This is a best-effort API. Support depends on the terminal emulator and
+environment — for example, some terminal multiplexers (such as tmux) do not
+respond to this query at all, and some terminals have been observed to
+respond with incorrect values. Results should not be treated as
+authoritative, and callers should have a fallback for when the Promise
+resolves to `undefined`.
+
 ### `writeStream.getColorDepth([env])`
 
 <!-- YAML
diff --git a/lib/tty.js b/lib/tty.js
index b1a2d3e7a9bc..aabd44fd66a8 100644
--- a/lib/tty.js
+++ b/lib/tty.js
@@ -127,6 +127,20 @@ WriteStream.prototype.getColorDepth = getColorDepth;
 
 WriteStream.prototype.hasColors = hasColors;
 
+// Queries the terminal for its background color via the OSC 11 escape
+// sequence. Best-effort: resolves `undefined` if the terminal does not
+// respond within the timeout or does not support the query.
+WriteStream.prototype.getBackgroundColor = function() {
+  return new Promise((resolve) => {
+    // TODO: write the OSC 11 query sequence to this stream, listen for
+    // the response on a 'data' handler, parse the RGB reply, guard
+    // against known-unresponsive environments (e.g. tmux) and against
+    // leaking unconsumed bytes back into the stream, and enforce a
+    // timeout. For now this stub always resolves `undefined`.
+    resolve(undefined);
+  });
+};
+
 WriteStream.prototype._refreshSize = function() {
   const oldCols = this.columns;
   const oldRows = this.rows;
diff --git a/test/parallel/test-tty-osc11-bg-color.js b/test/parallel/test-tty-osc11-bg-color.js
new file mode 100644
index 000000000000..5372d1d9d099
--- /dev/null
+++ b/test/parallel/test-tty-osc11-bg-color.js
@@ -0,0 +1,18 @@
+'use strict';
+const common = require('../common');
+
+if (!common.isMainThread)
+  common.skip('process.stdout is not a tty in Workers');
+
+const assert = require('assert');
+const tty = require('tty');
+
+// Placeholder test: just verifies the API surface exists and returns
+// a Promise. Real OSC 11 protocol/timeout tests will be added once
+// the implementation is complete.
+const stream = new tty.WriteStream(1);
+
+assert.strictEqual(typeof stream.getBackgroundColor, 'function');
+
+const result = stream.getBackgroundColor();
+assert.ok(result instanceof Promise);
\ No newline at end of file

From a123a2d2853ae5e1de91c3c05c12300e2daaa6be Mon Sep 17 00:00:00 2001
From: nirupam <153449247+nirupam-06@users.noreply.github.com>
Date: Sat, 8 Aug 2026 08:23:20 +0530
Subject: [PATCH 2/3] Update doc/api/tty.md

Co-authored-by: Aviv Keller <me@aviv.sh>
---
 doc/api/tty.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/doc/api/tty.md b/doc/api/tty.md
index 89c28adeb523..69d48e63952b 100644
--- a/doc/api/tty.md
+++ b/doc/api/tty.md
@@ -212,7 +212,6 @@ changes:
 `writeStream.cursorTo()` moves this `WriteStream`'s cursor to the specified
 position.
 
-
 ### `writeStream.getBackgroundColor()`
 
 <!-- YAML

From 2e26ce71022fb881f63e1fe38e5723a24ecec328 Mon Sep 17 00:00:00 2001
From: nirupamzenith <sainirupamkakani@gmail.com>
Date: Sat, 8 Aug 2026 09:04:15 +0530
Subject: [PATCH 3/3] tty: implement OSC 11 background color query

Signed-off-by: nirupamzenith <sainirupamkakani@gmail.com>
---
 lib/tty.js                               | 120 +++++++++++++++++++++--
 test/parallel/test-tty-osc11-bg-color.js |  22 ++++-
 2 files changed, 128 insertions(+), 14 deletions(-)

diff --git a/lib/tty.js b/lib/tty.js
index aabd44fd66a8..f4f1aec004b0 100644
--- a/lib/tty.js
+++ b/lib/tty.js
@@ -127,17 +127,119 @@ WriteStream.prototype.getColorDepth = getColorDepth;
 
 WriteStream.prototype.hasColors = hasColors;
 
+
 // Queries the terminal for its background color via the OSC 11 escape
-// sequence. Best-effort: resolves `undefined` if the terminal does not
-// respond within the timeout or does not support the query.
-WriteStream.prototype.getBackgroundColor = function() {
+// sequence (`\x1b]11;?\x07`). Best-effort: resolves `undefined` if the
+// terminal does not respond within the timeout, does not support the
+// query, or is running under an environment known not to answer it
+// (e.g. GNU Screen, some tmux configurations).
+//
+// The response to an OSC query does not arrive on the write side of the
+// stream -- terminals reply as if the user had typed the response, so it
+// must be read back separately. We first try opening a short-lived
+// raw-mode ReadStream on the same underlying fd (this covers Unix ptys,
+// where a single fd is bidirectional), falling back to the process's
+// real stdin fd (0) if that isn't supported (e.g. Windows, where output
+// and input use separate handles). We always tear the reader down
+// (restoring cooked mode and removing listeners) on every exit path, so
+// a terminal that responds incorrectly or not at all can never leak
+// bytes into the user's real input stream.
+WriteStream.prototype.getBackgroundColor = function(options = {}) {
+  const { timeout = 200 } = options;
+
   return new Promise((resolve) => {
-    // TODO: write the OSC 11 query sequence to this stream, listen for
-    // the response on a 'data' handler, parse the RGB reply, guard
-    // against known-unresponsive environments (e.g. tmux) and against
-    // leaking unconsumed bytes back into the stream, and enforce a
-    // timeout. For now this stub always resolves `undefined`.
-    resolve(undefined);
+    const env = process.env;
+    if (env.TERM === 'screen' && !env.TERM_PROGRAM) {
+      resolve(undefined);
+      return;
+    }
+
+    if (!this.isTTY) {
+      resolve(undefined);
+      return;
+    }
+
+    let settled = false;
+    let reader;
+    let timer;
+    let buffer = '';
+
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      if (reader) {
+        reader.removeListener('data', onData);
+        try {
+          reader.setRawMode(false);
+        } catch {
+          // Not fatal -- fd may already be closed or unsupported.
+        }
+        reader.destroy();
+      }
+    };
+
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(value);
+    };
+
+    const onData = (chunk) => {
+      buffer += chunk.toString('latin1');
+
+      const belIndex = buffer.indexOf('\x07');
+      const stIndex = buffer.indexOf('\x1b\\');
+      const termIndex = belIndex === -1 ? stIndex :
+        (stIndex === -1 ? belIndex : Math.min(belIndex, stIndex));
+
+      if (termIndex === -1) return;
+
+      const reply = buffer.slice(0, termIndex);
+      const match = /rgb:([0-9a-f]{2,4})\/([0-9a-f]{2,4})\/([0-9a-f]{2,4})/i
+        .exec(reply);
+
+      if (!match) {
+        finish(undefined);
+        return;
+      }
+
+      const toByte = (hex) => parseInt(hex.slice(0, 2), 16);
+
+      finish({
+        r: toByte(match[1]),
+        g: toByte(match[2]),
+        b: toByte(match[3]),
+      });
+    };
+
+    // Some platforms (e.g. Windows) use separate handles for a terminal's
+    // input and output, so the same fd used for writing cannot always be
+    // put into raw read mode. Try the write-side fd first (this covers
+    // Unix ptys, where a single fd is bidirectional), and fall back to
+    // the process's real stdin fd if that fails.
+    const tryOpenReader = (fd) => {
+      const candidate = new ReadStream(fd);
+      candidate.setRawMode(true);
+      return candidate;
+    };
+
+    try {
+      reader = tryOpenReader(this._handle.fd);
+    } catch {
+      try {
+        reader = tryOpenReader(0);
+      } catch {
+        finish(undefined);
+        return;
+      }
+    }
+
+    reader.on('data', onData);
+
+    timer = setTimeout(() => finish(undefined), timeout);
+    timer.unref();
+
+    this.write('\x1b]11;?\x07');
   });
 };
 
diff --git a/test/parallel/test-tty-osc11-bg-color.js b/test/parallel/test-tty-osc11-bg-color.js
index 5372d1d9d099..242d36be9838 100644
--- a/test/parallel/test-tty-osc11-bg-color.js
+++ b/test/parallel/test-tty-osc11-bg-color.js
@@ -7,12 +7,24 @@ if (!common.isMainThread)
 const assert = require('assert');
 const tty = require('tty');
 
-// Placeholder test: just verifies the API surface exists and returns
-// a Promise. Real OSC 11 protocol/timeout tests will be added once
-// the implementation is complete.
+// getBackgroundColor() must always return a Promise, and that Promise
+// must settle (never hang forever) even when the terminal doesn't
+// respond. Use a short timeout override so this doesn't slow down CI
+// on machines without a responsive terminal attached.
 const stream = new tty.WriteStream(1);
 
 assert.strictEqual(typeof stream.getBackgroundColor, 'function');
 
-const result = stream.getBackgroundColor();
-assert.ok(result instanceof Promise);
\ No newline at end of file
+const result = stream.getBackgroundColor({ timeout: 50 });
+assert.ok(result instanceof Promise);
+
+result.then(common.mustCall((color) => {
+  if (color !== undefined) {
+    assert.strictEqual(typeof color.r, 'number');
+    assert.strictEqual(typeof color.g, 'number');
+    assert.strictEqual(typeof color.b, 'number');
+    for (const channel of [color.r, color.g, color.b]) {
+      assert.ok(channel >= 0 && channel <= 255);
+    }
+  }
+}));
\ No newline at end of file