Gate DEC private modes by capabilities

Author: xoofx

doc/readme.md

@@ -63,13 +63,15 @@ var caps = AnsiCapabilities.Default with
     AnsiEnabled = true,
     ColorLevel = AnsiColorLevel.Colors256,
     SupportsOsc8 = false,
+    SupportsPrivateModes = false,
 };
 
 using var builder = new AnsiBuilder();
 var w = new AnsiWriter(builder, caps);
 ```
 
 If `AnsiEnabled` is `false`, style/cursor/hyperlink methods become no-ops (text still writes).
+If `SupportsPrivateModes` is `false`, DEC private-mode helpers (for example `CursorVisible(...)`, `AlternateScreen(...)`, `PrivateMode(...)`) become no-ops.
 
 ### Colors and decorations
 
@@ -363,6 +365,8 @@ Decoration parameters used by `Decorate(...)` / `Undecorate(...)`:
 
 #### DEC private modes (CSI with `?`)
 
+These helpers emit sequences only when `AnsiCapabilities.SupportsPrivateModes` is `true`.
+
 | API | Emits | Notes |
 |---|---|---|
 | `CursorVisible(true)` / `ShowCursor(true)` | `ESC[?25h` | Show cursor |

readme.md

@@ -12,7 +12,7 @@ XenoAtom.Ansi is a fast, allocation-friendly .NET library for building rich ANSI
   - `AnsiWriter` fluent API (writes to `TextWriter` or `IBufferWriter<char>`)
   - `AnsiMarkup` for markup strings, including interpolated strings (formatted values are escaped)
   - SGR styling: colors (basic-16, 256-color, truecolor RGB), decorations (bold/dim/italic/underline/etc), reset
-  - Capability-aware output (`AnsiCapabilities`) including color downgrading and optional safe-mode behavior
+  - Capability-aware output (`AnsiCapabilities`) including color downgrading, private-mode gating, and optional safe-mode behavior
   - Cursor/screen helpers (ANSI/DEC/xterm/Windows Terminal): move/position, save/restore, erase (incl. scrollback), insert/delete chars/lines, scrolling + scroll regions, cursor style, mode toggles, tabs, alternate screen, soft reset
   - OSC helpers with configurable terminator (BEL or ST): window title (OSC 0/2), palette edits (OSC 4), hyperlinks (OSC 8)
 - **Parsing**

src/XenoAtom.Ansi.Tests/AnsiWriterTerminalControlTests.cs

@@ -119,4 +119,39 @@ public void ModeControls_ParseAsCsiWithPrivateMarkerWhenDec()
         Assert.AreEqual('?', decrst.PrivateMarker);
         CollectionAssert.AreEqual(new[] { 2004 }, decrst.Parameters);
     }
+
+    [TestMethod]
+    public void SupportsPrivateModes_DefaultsToTrue()
+    {
+        Assert.IsTrue(AnsiCapabilities.Default.SupportsPrivateModes);
+        Assert.IsTrue(new AnsiCapabilities().SupportsPrivateModes);
+    }
+
+    [TestMethod]
+    public void PrivateModeControls_AreNoOp_WhenPrivateModesAreNotSupported()
+    {
+        var caps = AnsiCapabilities.Default with { SupportsPrivateModes = false };
+
+        var output = AnsiRoundTrip.Emit(w =>
+        {
+            w.PrivateMode(2004, enabled: true);
+            w.PrivateMode(2004, enabled: false);
+            w.CursorKeysApplicationMode(enabled: true);
+            w.CursorKeysApplicationMode(enabled: false);
+            w.CursorBlinking(enabled: true);
+            w.CursorBlinking(enabled: false);
+            w.Columns132(enabled: true);
+            w.Columns132(enabled: false);
+            w.ShowCursor(visible: false);
+            w.ShowCursor(visible: true);
+            w.CursorVisible(visible: false);
+            w.CursorVisible(visible: true);
+            w.EnterAlternateScreen();
+            w.LeaveAlternateScreen();
+            w.AlternateScreen(enabled: true);
+            w.AlternateScreen(enabled: false);
+        }, caps);
+
+        Assert.AreEqual(string.Empty, output);
+    }
 }

src/XenoAtom.Ansi/AnsiCapabilities.cs

@@ -22,6 +22,7 @@ public record AnsiCapabilities
         AnsiEnabled = true,
         ColorLevel = AnsiColorLevel.TrueColor,
         SupportsOsc8 = true,
+        SupportsPrivateModes = true,
         Prefer7BitC1 = true,
         SafeMode = false,
         OscTermination = AnsiOscTermination.StringTerminator,
@@ -42,6 +43,11 @@ public record AnsiCapabilities
     /// </summary>
     public bool SupportsOsc8 { get; init; }
 
+    /// <summary>
+    /// Gets a value indicating whether DEC private mode sequences (<c>CSI ? ...</c>) should be emitted.
+    /// </summary>
+    public bool SupportsPrivateModes { get; init; } = true;
+
     /// <summary>
     /// Gets a value indicating whether the output should prefer 7-bit escape sequences (e.g. <c>ESC [</c>)
     /// instead of 8-bit C1 control codes (e.g. CSI as a single byte).

src/XenoAtom.Ansi/AnsiWriter.cs

@@ -877,7 +877,7 @@ public AnsiWriter SetMode(int mode, bool enabled)
     /// <returns>This writer, for fluent chaining.</returns>
     public AnsiWriter PrivateMode(int mode, bool enabled)
     {
-        if (!Capabilities.AnsiEnabled)
+        if (!CanEmitPrivateModes())
         {
             return this;
         }
@@ -931,13 +931,7 @@ public AnsiWriter CursorStyle(AnsiCursorStyle style)
     /// <returns>This writer, for fluent chaining.</returns>
     public AnsiWriter ShowCursor(bool visible)
     {
-        if (!Capabilities.AnsiEnabled)
-        {
-            return this;
-        }
-
-        Write(visible ? "\x1b[?25h" : "\x1b[?25l");
-        return this;
+        return PrivateMode(25, visible);
     }
 
     /// <summary>
@@ -953,13 +947,7 @@ public AnsiWriter ShowCursor(bool visible)
     /// <returns>This writer, for fluent chaining.</returns>
     public AnsiWriter EnterAlternateScreen()
     {
-        if (!Capabilities.AnsiEnabled)
-        {
-            return this;
-        }
-
-        Write("\x1b[?1049h");
-        return this;
+        return PrivateMode(1049, enabled: true);
     }
 
     /// <summary>
@@ -968,13 +956,7 @@ public AnsiWriter EnterAlternateScreen()
     /// <returns>This writer, for fluent chaining.</returns>
     public AnsiWriter LeaveAlternateScreen()
     {
-        if (!Capabilities.AnsiEnabled)
-        {
-            return this;
-        }
-
-        Write("\x1b[?1049l");
-        return this;
+        return PrivateMode(1049, enabled: false);
     }
 
     /// <summary>
@@ -1184,6 +1166,8 @@ private void WriteCsiWithInt(int n, char final, bool allowZeroToOmit = false)
         WriteChar(final);
     }
 
+    private bool CanEmitPrivateModes() => Capabilities.AnsiEnabled && Capabilities.SupportsPrivateModes;
+
     private void WriteSgr(string parameters)
     {
         if (!Capabilities.AnsiEnabled)