XenoAtom.Ansi

https://github.com/xenoatom/xenoatom.ansi
Admin
XenoAtom.Ansi is a fast, allocation-friendly .NET library for generating, parsing, and manipulating...
Tokens:47,628
Snippets:283
Trust Score:8.6
License:BSD-2-Clause
Update:2 days ago
Show doc for...
Tokens:
Raw
### Render basic markup with AnsiMarkup.Render

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Parses a markup string and returns the corresponding ANSI sequence string. The example applies bold, yellow foreground, and blue background to the word 'Warning'.

```csharp
var s = AnsiMarkup.Render("[bold yellow on blue]Warning[/] disk is almost full");
```

--------------------------------

### Get basic-16 RGB approximation

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Shows how to obtain an RGB approximation for a basic-16 palette index using AnsiPalettes.GetBasic16Rgb. The result is a tuple of (R,G,B) values.

```csharp
var rgb = AnsiPalettes.GetBasic16Rgb(AnsiColors.Red.Index); // (R,G,B) approximation
```

--------------------------------

### Custom token dictionary with AnsiMarkup

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Creates a custom token dictionary mapping tokens like '[primary]' and '[error]' to AnsiStyle objects. Token lookup is case-insensitive and avoids per-token string allocations. The example writes styled output using an AnsiBuilder and AnsiWriter.

```csharp
var tokens = new Dictionary<string, AnsiStyle>(StringComparer.OrdinalIgnoreCase)
{
    ["primary"] = new AnsiStyle { Foreground = AnsiColors.Web.CornflowerBlue },
    ["error"]   = new AnsiStyle { Foreground = AnsiColors.BrightRed, Decorations = AnsiDecorations.Bold },
};

using var builder = new AnsiBuilder();
var w = new AnsiWriter(builder);
var m = new AnsiMarkup(w, tokens);

m.Write("[primary]info[/] [error]boom[/]");
```

--------------------------------

### Interpolated values are escaped automatically

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Shows that user input interpolated into the markup string is escaped, so markup tags in the input are not interpreted. The example renders the literal text '[red]not actually red[/]' in red.

```csharp
var userInput = "[red]not actually red[/]";
var s = AnsiMarkup.Render($"[red]{userInput}[/]");
```

--------------------------------

### Run HelloWorld sample

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/readme.md

Command to run the HelloWorld sample project, which demonstrates basic formatting across a few lines.

```bash
dotnet run --project samples/HelloWorld/HelloWorld.csproj
```

--------------------------------

### Run HelloAdvanced sample

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/readme.md

Command to run the HelloAdvanced sample project, which demonstrates richer features like colors, decorations, markup, OSC 8 links, and screen helpers.

```bash
dotnet run --project samples/HelloAdvanced/HelloAdvanced.csproj
```

--------------------------------

### Build and test commands

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/AGENTS.md

Commands to build the solution in Release configuration and run all tests. Run from the 'src' directory.

```sh
cd src
dotnet build -c Release
dotnet test -c Release
```

--------------------------------

### AnsiWriter Constructor and Basic Usage

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Creates an AnsiWriter with an AnsiBuilder and demonstrates basic fluent output.

```APIDOC
## AnsiWriter Constructor and Basic Usage

### Description
Creates an AnsiWriter instance and uses its fluent API to emit styled text.

### Method
Constructor

### Endpoint
`new AnsiWriter(AnsiBuilder builder)`

### Parameters
#### Constructor Parameters
- **builder** (AnsiBuilder) - Required - The builder that receives the emitted output.

### Request Example
```csharp
using var builder = new AnsiBuilder();
var w = new AnsiWriter(builder);

w.Foreground(AnsiColors.BrightYellow)
 .Decorate(AnsiDecorations.Bold)
 .Write("Warning: ")
 .ResetStyle()
 .Write("disk is almost full");

var s = builder.ToString();
```

### Response
#### Success Response
- **builder.ToString()** (string) - The accumulated output string.

#### Response Example
```csharp
var s = builder.ToString();
```
```

--------------------------------

### AnsiMarkup constructor and Write method

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Constructs an AnsiMarkup instance with an AnsiWriter and optional custom token dictionary, and writes markup to the writer.

```APIDOC
## AnsiMarkup Constructor and Write Method

### Description
Constructs an AnsiMarkup instance with an AnsiWriter and optional custom token dictionary, and writes markup to the writer.

### Constructor
`AnsiMarkup(AnsiWriter writer, Dictionary<string, AnsiStyle> tokens = null)`

### Parameters
- **writer** (AnsiWriter) - Required - The writer to emit ANSI sequences.
- **tokens** (Dictionary<string, AnsiStyle>) - Optional - Custom token dictionary. Token lookup is case-insensitive and avoids per-token string allocations.

### Method
`Write(string markup)`

### Parameters
- **markup** (string) - Required - The markup string to write.

### Example
```csharp
var tokens = new Dictionary<string, AnsiStyle>(StringComparer.OrdinalIgnoreCase)
{
    ["primary"] = new AnsiStyle { Foreground = AnsiColors.Web.CornflowerBlue },
    ["error"]   = new AnsiStyle { Foreground = AnsiColors.BrightRed, Decorations = AnsiDecorations.Bold },
};

using var builder = new AnsiBuilder();
var w = new AnsiWriter(builder);
var m = new AnsiMarkup(w, tokens);

m.Write("[primary]info[/] [error]boom[/]");
```
```

--------------------------------

### Basic AnsiWriter usage with AnsiBuilder

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Creates an AnsiBuilder and AnsiWriter, then uses the fluent API to write a styled warning message. The output is obtained via builder.ToString().

```csharp
using var builder = new AnsiBuilder();
var w = new AnsiWriter(builder);

w.Foreground(AnsiColors.BrightYellow)
 .Decorate(AnsiDecorations.Bold)
 .Write("Warning: ")
 .ResetStyle()
 .Write("disk is almost full");

var s = builder.ToString();
```

--------------------------------

### Decorations and undecorate

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Applies underline and bold decorations, then removes underline while keeping bold, and resets style.

```csharp
w.Decorate(AnsiDecorations.Underline | AnsiDecorations.Bold).Write("emphasis");
w.Undecorate(AnsiDecorations.Underline).Write("still bold");
w.ResetStyle();
```

--------------------------------

### OSC (Operating System Command)

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Helpers that emit OSC sequences for window title, palette, hyperlinks, and generic OSC commands.

```APIDOC
## WindowTitle(title)

### Description
Sets the window title using OSC 2 by emitting `ESC]2;<title>` followed by the configured terminator.

### Method
OSC

### Parameters
- **title** (string) - Required - The window title.

### Emits
`ESC]2;<title>` + terminator

### Notes
OSC 2 window title

---

## IconAndWindowTitle(title)

### Description
Sets both the icon and window title using OSC 0 by emitting `ESC]0;<title>` followed by the configured terminator.

### Method
OSC

### Parameters
- **title** (string) - Required - The icon and window title.

### Emits
`ESC]0;<title>` + terminator

### Notes
OSC 0 icon + window title

---

## SetPaletteColor(i,r,g,b)

### Description
Sets a palette color entry using OSC 4 by emitting `ESC]4;<i>;rgb:<rr>/<gg>/<bb>` followed by the configured terminator.

### Method
OSC

### Parameters
- **i** (integer) - Required - The palette index.
- **r** (integer) - Required - The red component (0-255).
- **g** (integer) - Required - The green component (0-255).
- **b** (integer) - Required - The blue component (0-255).

### Emits
`ESC]4;<i>;rgb:<rr>/<gg>/<bb>` + terminator

### Notes
OSC 4 palette entry

---

## BeginLink(uri, id)

### Description
Begins an OSC 8 hyperlink by emitting `ESC]8;id=<id>;<uri>` followed by the configured terminator. The `id` parameter is optional.

### Method
OSC

### Parameters
- **uri** (string) - Required - The hyperlink URI.
- **id** (string) - Optional - The hyperlink ID.

### Emits
`ESC]8;id=<id>;<uri>` + terminator

### Notes
OSC 8 hyperlink (id is optional)

---

## EndLink()

### Description
Ends an OSC 8 hyperlink by emitting `ESC]8;;` followed by the configured terminator.

### Method
OSC

### Emits
`ESC]8;;` + terminator

### Notes
Ends OSC 8 hyperlink

---

## WriteOsc(code,payload)

### Description
Writes a generic OSC command safely by emitting `ESC]<code>;<payload>` followed by the configured terminator.

### Method
OSC

### Parameters
- **code** (integer) - Required - The OSC command code.
- **payload** (string) - Required - The OSC payload.

### Emits
`ESC]<code>;<payload>` + terminator

### Notes
Generic safe OSC writer

---

## AnsiCapabilities.OscTermination

### Description
Specifies the terminator used for OSC sequences.

### Values
- **AnsiOscTermination.StringTerminator** - Emits `ESC\` (ST)
- **AnsiOscTermination.Bell** - Emits `BEL` (`\x07`)
```

--------------------------------

### Minimal style transition

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Tracks current style and emits only the delta using StyleTransition. Minimizes ESC[0m usage unless AnsiCapabilities.SafeMode is enabled.

```csharp
var current = AnsiStyle.Default;
var next = current with { Foreground = AnsiColors.Green };

w.StyleTransition(current, next).Write("OK");
current = next;
```

--------------------------------

### Apply reusable AnsiStyle

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Defines a reusable AnsiStyle with foreground and decorations, then applies it with Style and resets.

```csharp
var title = new AnsiStyle
{
    Foreground = AnsiColors.Cyan,
    Decorations = AnsiDecorations.Bold,
};

w.Style(title).Write("Title").ResetStyle();
```

--------------------------------

### Styling via AnsiStyle

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Applies a reusable AnsiStyle object to the writer.

```APIDOC
## Styling via AnsiStyle

### Description
Applies a pre-defined `AnsiStyle` to the writer.

### Method
- `Style(AnsiStyle style)` - Applies the given style.
- `ResetStyle()` - Resets the style to default.

### Parameters
#### Method Parameters
- **style** (AnsiStyle) - Required - The style to apply.

### Request Example
```csharp
var title = new AnsiStyle
{
    Foreground = AnsiColors.Cyan,
    Decorations = AnsiDecorations.Bold,
};

w.Style(title).Write("Title").ResetStyle();
```

### Response
#### Success Response
- **builder.ToString()** (string) - The accumulated output string.

#### Response Example
```csharp
var s = builder.ToString();
```
```

--------------------------------

### Alternate screen for full-screen UIs

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Enables and disables the alternate screen buffer.

```csharp
w.AlternateScreen(true);
// ...
w.AlternateScreen(false);
```

--------------------------------

### ANSI-aware text utilities with AnsiText

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Shows usage of AnsiText methods: Strip removes escape sequences, GetVisibleWidth computes visible width using Wcwidth, Wrap wraps text to a given width, and Truncate truncates with an ellipsis.

```csharp
var plain = AnsiText.Strip("a\u001b[31mb".AsSpan());          // "ab"
var width = AnsiText.GetVisibleWidth("a界b".AsSpan());       // 4 (界 is width 2)
var wrapped = AnsiText.Wrap("abcd", width: 2, preserveAnsi: false);
var truncated = AnsiText.Truncate("hello world", width: 5);  // "hell…"
```

--------------------------------

### AnsiKittyGraphicsSequences.TryParseReply

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Parses the common Kitty graphics APC reply shape into an AnsiKittyGraphicsReply for probe coordination.

```APIDOC
## AnsiKittyGraphicsSequences.TryParseReply

### Description
Parses the common Kitty graphics APC reply shape into an `AnsiKittyGraphicsReply` for probe coordination.

### Method
TryParseReply

### Parameters
- (input) The APC reply data (implicit)
- `out AnsiKittyGraphicsReply` - Output parameter that receives the parsed reply.

### Returns
- `bool` - `true` if parsing succeeds; otherwise `false`.
```

--------------------------------

### Foreground and background colors

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Sets foreground and background colors using AnsiColors, then resets the style.

```csharp
w.Foreground(AnsiColors.Red).Write("red");
w.Background(AnsiColors.Blue).Write("on blue");
w.ResetStyle();
```

--------------------------------

### Minimal Style Transitions

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Applies only the delta between the current style and a new style to minimize escape sequences.

```APIDOC
## Minimal Style Transitions

### Description
Applies a style transition from a current style to a new style, emitting only the differences.

### Method
- `StyleTransition(AnsiStyle current, AnsiStyle next)` - Applies the transition.

### Parameters
#### Method Parameters
- **current** (AnsiStyle) - Required - The current style.
- **next** (AnsiStyle) - Required - The new style to transition to.

### Request Example
```csharp
var current = AnsiStyle.Default;
var next = current with { Foreground = AnsiColors.Green };

w.StyleTransition(current, next).Write("OK");
current = next;
```

### Response
#### Success Response
- **builder.ToString()** (string) - The accumulated output string.

#### Response Example
```csharp
var s = builder.ToString();
```
```

--------------------------------

### CsiToken.TryGetSgrMouseEvent

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Decodes an SGR mouse event sequence into an AnsiMouseEvent. Use this to parse mouse input in SGR mode.

```APIDOC
## CsiToken.TryGetSgrMouseEvent

### Description
Decodes an SGR mouse event sequence (`ESC[<b;x;yM/m`) into an `AnsiMouseEvent`.

### Method
TryGetSgrMouseEvent

### Parameters
- `out AnsiMouseEvent` - Output parameter that receives the parsed mouse event.

### Returns
- `bool` - `true` if the token represents a valid SGR mouse event; otherwise `false`.
```

--------------------------------

### AnsiWriter Input Sequence Helpers

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Instance methods on AnsiWriter that emit terminal input sequences for test and host scenarios. These helpers allow generating CPR, SGR mouse, and key event sequences.

```APIDOC
## AnsiWriter Input Sequence Helpers

### Description
Instance methods on `AnsiWriter` that emit terminal input sequences for test and host scenarios. These helpers allow generating CPR, SGR mouse, and key event sequences.

### Methods
- Emit CPR reply sequences
- Emit SGR mouse event sequences
- Emit key event sequences
```

--------------------------------

### AnsiText.Wrap

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Wraps text to a specified width, optionally preserving ANSI escape sequences.

```APIDOC
## AnsiText.Wrap

### Description
Wraps the input text to the given width, breaking lines at word boundaries. If preserveAnsi is true, escape sequences are kept in the output; otherwise they are stripped.

### Method
Wrap

### Signature
`static string Wrap(string text, int width, bool preserveAnsi = false)`

### Parameters
- **text** (string) - Required - The text to wrap.
- **width** (int) - Required - The maximum line width in columns.
- **preserveAnsi** (bool) - Optional - Whether to keep ANSI escape sequences in the output. Defaults to false.

### Return Value
The wrapped text.

### Example
```csharp
var wrapped = AnsiText.Wrap("abcd", width: 2, preserveAnsi: false);
```
```

--------------------------------

### Protocol-specific framing helpers

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Uses protocol-specific helpers for Kitty graphics, iTerm2 inline images, and Sixel. These helpers reject C0/C1 control characters in payloads and framing characters in protocol parameters.

```csharp
AnsiKittyGraphicsSequences.WriteCommand(w, "a=T,f=100".AsSpan(), "...base64...".AsSpan());
AnsiIterm2ImageSequences.WriteFile(w, "inline=1;width=10".AsSpan(), "...base64...".AsSpan());
AnsiSixelSequences.WriteImage(w, "0;1".AsSpan(), "...sixel payload...".AsSpan());
```

--------------------------------

### Queries

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Helpers that emit terminal query sequences (CSI).

```APIDOC
## RequestCursorPosition()

### Description
Requests the cursor position (DECXCPR) by emitting `ESC[6n`. The terminal typically replies with `ESC[<r>;<c>R`.

### Method
CSI

### Emits
`ESC[6n`

### Notes
DECXCPR; reply typically `ESC[<r>;<c>R`

---

## RequestDeviceAttributes()

### Description
Requests device attributes (DA) by emitting `ESC[c`. The terminal typically replies with `ESC[?...c`.

### Method
CSI

### Emits
`ESC[c`

### Notes
DA; reply typically `ESC[?...c`
```

--------------------------------

### Decorations

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Applies or removes text decorations such as bold, underline, etc.

```APIDOC
## Decorations

### Description
Applies or removes text decorations using `AnsiDecorations` flags.

### Methods
- `Decorate(AnsiDecorations decorations)` - Applies the specified decorations.
- `Undecorate(AnsiDecorations decorations)` - Removes the specified decorations.
- `ResetStyle()` - Resets the style to default.

### Parameters
#### Method Parameters
- **decorations** (AnsiDecorations) - Required - The decorations to apply or remove. Can be a combination of flags.

### Request Example
```csharp
w.Decorate(AnsiDecorations.Underline | AnsiDecorations.Bold).Write("emphasis");
w.Undecorate(AnsiDecorations.Underline).Write("still bold");
w.ResetStyle();
```

### Response
#### Success Response
- **builder.ToString()** (string) - The accumulated output string.

#### Response Example
```csharp
var s = builder.ToString();
```
```

--------------------------------

### Foreground and Background Colors

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Sets foreground and background colors using named colors, indexed 256-color, or truecolor RGB.

```APIDOC
## Foreground and Background Colors

### Description
Sets the foreground or background color using various color representations.

### Methods
- `Foreground(AnsiColor color)` - Sets the foreground color.
- `Background(AnsiColor color)` - Sets the background color.
- `ResetStyle()` - Resets the style to default.

### Parameters
#### Method Parameters
- **color** (AnsiColor) - Required - The color to set. Can be an `AnsiColors` constant, `AnsiColor.Indexed256(int)`, or `AnsiColor.Rgb(int, int, int)`.

### Request Example
```csharp
w.Foreground(AnsiColors.Red).Write("red");
w.Background(AnsiColors.Blue).Write("on blue");
w.ResetStyle();

w.Foreground(AnsiColor.Indexed256(208)).Write("orange-ish");

w.Foreground(AnsiColor.Rgb(255, 128, 0)).Write("rgb");
```

### Response
#### Success Response
- **builder.ToString()** (string) - The accumulated output string.

#### Response Example
```csharp
var s = builder.ToString();
```
```

--------------------------------

### Streaming chunked parsing with AnsiTokenizer

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Parses input that arrives in chunks by calling Tokenize multiple times, keeping isFinalChunk false until the final chunk. Tokens are accumulated in a provided list.

```csharp
using var tok = new AnsiTokenizer();
var tokens = new List<AnsiToken>();
tok.Tokenize("a\u001b[".AsSpan(), isFinalChunk: false, tokens);
tok.Tokenize("31mb".AsSpan(), isFinalChunk: true, tokens);
```

--------------------------------

### AnsiStyledTextParser.Parse

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Parses ANSI SGR and OSC 8 sequences into styled runs for rendering. Returns a list of runs with text and style information.

```APIDOC
## AnsiStyledTextParser.Parse

### Description
Interprets SGR (Select Graphic Rendition) and OSC 8 (hyperlink) escape sequences in the input text and produces a list of styled runs. Each run contains the visible text and its associated style (e.g., color).

### Method
Parse

### Signature
`IReadOnlyList<AnsiStyledRun> Parse(ReadOnlySpan<char> input)`

### Parameters
- **input** (ReadOnlySpan<char>) - Required - The ANSI-encoded text to parse.

### Return Value
A list of AnsiStyledRun objects, each with a Text property and a Style property (e.g., default or red).

### Example
```csharp
using var parser = new AnsiStyledTextParser();
var runs = parser.Parse("ab\u001b[31mcd\u001b[0mef".AsSpan());
// runs: ("ab", default), ("cd", red), ("ef", default)
```
```

--------------------------------

### AnsiWriter with AnsiCapabilities

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Creates an AnsiWriter with custom capabilities to gate output based on environment support.

```APIDOC
## AnsiWriter with AnsiCapabilities

### Description
Creates an AnsiWriter with an AnsiCapabilities instance to control feature gating.

### Method
Constructor

### Endpoint
`new AnsiWriter(AnsiBuilder builder, AnsiCapabilities caps)`

### Parameters
#### Constructor Parameters
- **builder** (AnsiBuilder) - Required - The builder that receives the emitted output.
- **caps** (AnsiCapabilities) - Required - The capabilities that determine which features are enabled.

### Request Example
```csharp
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);
```

### Response
#### Success Response
- **builder.ToString()** (string) - The accumulated output string.

#### Response Example
```csharp
var s = builder.ToString();
```
```

--------------------------------

### OSC 8 hyperlinks

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Emits an OSC 8 hyperlink when SupportsOsc8 is enabled.

```csharp
w.BeginLink("https://example.com").Write("click here").EndLink();
```

--------------------------------

### Configure AnsiCapabilities for feature gating

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Creates an AnsiCapabilities instance with specific settings and passes it to AnsiWriter. When AnsiEnabled is false, style/cursor/hyperlink methods become no-ops. When SupportsPrivateModes is false, DEC private-mode helpers become no-ops.

```csharp
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);
```

--------------------------------

### AnsiWriter SGR Methods

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Methods for emitting Select Graphic Rendition (SGR) sequences to set foreground, background, and styles.

```APIDOC
## AnsiWriter SGR Methods

### Description
Methods for emitting Select Graphic Rendition (SGR) sequences to set foreground, background, and styles.

### Methods

#### ResetStyle() / Reset()
- **Emits**: `ESC[0m`
- **Notes**: Resets all attributes.

#### Foreground(AnsiColor.Default)
- **Emits**: `ESC[39m`
- **Notes**: Default foreground.

#### Foreground(AnsiColor.Basic16(0..15))
- **Emits**: `ESC[30..37m` / `ESC[90..97m`
- **Notes**: 16-color palette.

#### Foreground(AnsiColor.Indexed256(0..255))
- **Emits**: `ESC[38;5;<n>m`
- **Notes**: 256-color indexed.

#### Foreground(AnsiColor.Rgb(r,g,b))
- **Emits**: `ESC[38;2;<r>;<g>;<b>m`
- **Notes**: May downgrade based on `AnsiCapabilities.ColorLevel`.

#### Background(AnsiColor.Default)
- **Emits**: `ESC[49m`
- **Notes**: Default background.

#### Background(AnsiColor.Basic16(0..15))
- **Emits**: `ESC[40..47m` / `ESC[100..107m`
- **Notes**: 16-color palette.

#### Background(AnsiColor.Indexed256(0..255))
- **Emits**: `ESC[48;5;<n>m`
- **Notes**: 256-color indexed.

#### Background(AnsiColor.Rgb(r,g,b))
- **Emits**: `ESC[48;2;<r>;<g>;<b>m`
- **Notes**: May downgrade based on `AnsiCapabilities.ColorLevel`.

#### Style(AnsiStyle)
- **Emits**: SGR sequence(s)
- **Notes**: Applies a style starting from the default style.

#### StyleTransition(from,to,...)
- **Emits**: SGR sequence(s)
- **Notes**: Minimal delta; more aggressive output when `AnsiCapabilities.SafeMode` is `true`.

### Decoration Parameters

| Decoration | Enable SGR | Disable SGR |
|---|---:|---:|
| Bold | `1` | `22` |
| Dim | `2` | `22` |
| Italic | `3` | `23` |
| Underline | `4` | `24` |
| Blink | `5` | `25` |
| Invert | `7` | `27` |
| Hidden | `8` | `28` |
| Strikethrough | `9` | `29` |
```

--------------------------------

### 256-color indexed color

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Uses AnsiColor.Indexed256 to set a 256-color indexed foreground.

```csharp
w.Foreground(AnsiColor.Indexed256(208)).Write("orange-ish");
```

--------------------------------

### AnsiToken.TryGetKeyEvent

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Decodes common key sequences (arrows, Home/End, Insert/Delete, F1–F12, etc.) into an AnsiKeyEvent. Recognizes Shift, Alt, and Control modifiers when reported.

```APIDOC
## AnsiToken.TryGetKeyEvent

### Description
Decodes common key sequences (arrows, Home/End, Insert/Delete, F1–F12, etc.) into an `AnsiKeyEvent`. Recognizes Shift, Alt, and Control modifiers when reported.

### Method
TryGetKeyEvent

### Parameters
- `out AnsiKeyEvent` - Output parameter that receives the parsed key event.

### Returns
- `bool` - `true` if the token represents a recognized key sequence; otherwise `false`.
```

--------------------------------

### OSC 8 Hyperlinks

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Emits OSC 8 hyperlinks when the capability is enabled.

```APIDOC
## OSC 8 Hyperlinks

### Description
Emits OSC 8 hyperlinks when `SupportsOsc8` is enabled.

### Methods
- `BeginLink(string uri)` - Begins a hyperlink with the given URI.
- `EndLink()` - Ends the current hyperlink.

### Parameters
#### Method Parameters
- **uri** (string) - Required - The hyperlink target URI.

### Request Example
```csharp
w.BeginLink("https://example.com").Write("click here").EndLink();
```

### Response
#### Success Response
- **builder.ToString()** (string) - The accumulated output string.

#### Response Example
```csharp
var s = builder.ToString();
```
```

--------------------------------

### Terminal String Controls and Graphics Protocol Framing

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Low-level helpers for DCS, SOS, PM, APC, and graphics protocol framing (Kitty, iTerm2, Sixel).

```APIDOC
## WriteDcs(payload)

### Description
Writes a generic DCS (Device Control String) by emitting `ESC P <payload> ESC\`.

### Method
DCS

### Parameters
- **payload** (string) - Required - The DCS payload.

### Emits
`ESC P <payload> ESC\`

### Notes
Generic DCS writer

---

## WriteSos(payload)

### Description
Writes a generic SOS (Start of String) by emitting `ESC X <payload> ESC\`.

### Method
SOS

### Parameters
- **payload** (string) - Required - The SOS payload.

### Emits
`ESC X <payload> ESC\`

### Notes
Generic SOS writer

---

## WritePm(payload)

### Description
Writes a generic PM (Privacy Message) by emitting `ESC ^ <payload> ESC\`.

### Method
PM

### Parameters
- **payload** (string) - Required - The PM payload.

### Emits
`ESC ^ <payload> ESC\`

### Notes
Generic PM writer

---

## WriteApc(payload)

### Description
Writes a generic APC (Application Program Command) by emitting `ESC _ <payload> ESC\`.

### Method
APC

### Parameters
- **payload** (string) - Required - The APC payload.

### Emits
`ESC _ <payload> ESC\`

### Notes
Generic APC writer

---

## AnsiKittyGraphicsSequences.WriteCommand(...)

### Description
Writes a Kitty graphics command using APC framing by emitting `ESC _ G ... ESC\`.

### Method
APC

### Emits
`ESC _ G ... ESC\`

### Notes
Kitty graphics APC framing for prepared parameters/base64 payloads

---

## AnsiKittyGraphicsSequences.WriteCommandChunks(...)

### Description
Writes Kitty graphics commands in chunks by emitting multiple `ESC _ G ... m=... ; chunk ESC\` commands.

### Method
APC

### Emits
Multiple `ESC _ G ... m=... ; chunk ESC\` commands

### Notes
Adds Kitty `m=1`/`m=0` chunk flags

---

## AnsiIterm2ImageSequences.WriteFile(...)

### Description
Writes an iTerm2 inline image using OSC framing by emitting `ESC]1337;File=...:<payload>` followed by the configured terminator.

### Method
OSC

### Emits
`ESC]1337;File=...:<payload>` + terminator

### Notes
iTerm2 inline image OSC framing

---

## AnsiSixelSequences.WriteImage(...)

### Description
Writes a Sixel image using DCS framing by emitting `ESC P <params> q <payload> ESC\`.

### Method
DCS

### Emits
`ESC P <params> q <payload> ESC\`

### Notes
Sixel DCS framing for an already-encoded Sixel payload
```

--------------------------------

### Terminal String Controls and Graphics Protocol Framing

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Provides low-level methods to write OSC, DCS, and APC sequences, and protocol-specific framing helpers.

```APIDOC
## Terminal String Controls and Graphics Protocol Framing

### Description
Provides safe low-level methods to write OSC, DCS, and APC sequences, and protocol-specific framing helpers for image transports.

### Methods
- `WriteOsc(int command, ReadOnlySpan<char> payload)` - Writes an OSC sequence.
- `WriteDcs(ReadOnlySpan<char> payload)` - Writes a DCS sequence.
- `WriteApc(ReadOnlySpan<char> payload)` - Writes an APC sequence.

### Protocol-Specific Helpers
- `AnsiKittyGraphicsSequences.WriteCommand(AnsiWriter w, ReadOnlySpan<char> params, ReadOnlySpan<char> payload)` - Writes a Kitty graphics protocol command.
- `AnsiIterm2ImageSequences.WriteFile(AnsiWriter w, ReadOnlySpan<char> params, ReadOnlySpan<char> payload)` - Writes an iTerm2 image protocol file.
- `AnsiSixelSequences.WriteImage(AnsiWriter w, ReadOnlySpan<char> params, ReadOnlySpan<char> payload)` - Writes a Sixel image.

### Parameters
#### Method Parameters
- **command** (int) - Required - The OSC command number.
- **payload** (ReadOnlySpan<char>) - Required - The payload to write.
- **params** (ReadOnlySpan<char>) - Required - Protocol parameters.

### Request Example
```csharp
w.WriteOsc(1337, "File=inline=1:...base64...".AsSpan());
w.WriteDcs("0;1q...sixel payload...".AsSpan());
w.WriteApc("Gf=100;...base64...".AsSpan());

AnsiKittyGraphicsSequences.WriteCommand(w, "a=T,f=100".AsSpan(), "...base64...".AsSpan());
AnsiIterm2ImageSequences.WriteFile(w, "inline=1;width=10".AsSpan(), "...base64...".AsSpan());
AnsiSixelSequences.WriteImage(w, "0;1".AsSpan(), "...sixel payload...".AsSpan());
```

### Response
#### Success Response
- **builder.ToString()** (string) - The accumulated output string.

#### Response Example
```csharp
var s = builder.ToString();
```
```

--------------------------------

### Parse styled runs with AnsiStyledTextParser

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Parses a string containing SGR escape sequences into styled runs. The comment shows the expected runs: ("ab", default), ("cd", red), ("ef", default).

```csharp
using var parser = new AnsiStyledTextParser();
var runs = parser.Parse("ab\u001b[31mcd\u001b[0mef".AsSpan());
// runs: ("ab", default), ("cd", red), ("ef", default)
```

--------------------------------

### Tokenize a complete ANSI string with AnsiTokenizer

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Creates an AnsiTokenizer and tokenizes a span containing ANSI escape sequences. The isFinalChunk parameter is set to true to indicate the input is complete.

```csharp
using var tok = new AnsiTokenizer();
var tokens = tok.Tokenize("a\u001b[31mb".AsSpan(), isFinalChunk: true);
```

--------------------------------

### AnsiStyledTextParser

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Provides a higher-level 'runs' view intended for rendering. Applies SgrToken operations to produce AnsiStyle changes per run and interprets OSC 8 hyperlinks.

```APIDOC
## AnsiStyledTextParser

### Description
Provides a higher-level 'runs' view intended for rendering. Applies `SgrToken` operations to produce `AnsiStyle` changes per run and interprets OSC 8 hyperlinks.

### Behavior
- Applies `SgrToken` operations to produce `AnsiStyle` changes per run.
- Interprets OSC 8 (`OscToken` with `Code == 8`) to track an active hyperlink per run.
- Does not interpret cursor movement/erasure; runs are produced in source order.
```

--------------------------------

### AnsiText.GetVisibleWidth

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Computes the display width of the visible text, accounting for wide characters (e.g., CJK) using the Wcwidth package.

```APIDOC
## AnsiText.GetVisibleWidth

### Description
Calculates the number of terminal columns needed to display the input text, ignoring escape sequences and using Unicode width rules for wide characters.

### Method
GetVisibleWidth

### Signature
`static int GetVisibleWidth(ReadOnlySpan<char> input)`

### Parameters
- **input** (ReadOnlySpan<char>) - Required - The text to measure.

### Return Value
The visible width in columns.

### Example
```csharp
var width = AnsiText.GetVisibleWidth("a界b".AsSpan()); // 4 (界 is width 2)
```
```

--------------------------------

### Soft Reset

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Helper that emits the soft reset sequence (CSI with intermediate '!').

```APIDOC
## SoftReset()

### Description
Performs a soft reset by emitting the sequence `ESC[!p`.

### Method
CSI

### Emits
`ESC[!p`

### Notes
"Soft reset"
```

--------------------------------

### Cursor and Erase Helpers

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Provides methods to move the cursor, erase lines, and control cursor visibility.

```APIDOC
## Cursor and Erase Helpers

### Description
Provides methods to move the cursor, erase lines, and control cursor visibility.

### Methods
- `Up(int count)` - Moves the cursor up by the specified number of lines.
- `EraseLine(int mode)` - Erases the current line according to the mode.
- `MoveTo(int column, int row)` - Moves the cursor to the specified 1-based position.
- `CursorVisible(bool visible)` - Shows or hides the cursor (requires `SupportsPrivateModes`).
- `AlternateScreen(bool enable)` - Switches to or from the alternate screen buffer (requires `SupportsPrivateModes`).

### Parameters
#### Method Parameters
- **count** (int) - Required - Number of lines to move up.
- **mode** (int) - Required - Erase mode (e.g., 2 clears entire line).
- **column** (int) - Required - 1-based column position.
- **row** (int) - Required - 1-based row position.
- **visible** (bool) - Required - Whether the cursor should be visible.
- **enable** (bool) - Required - Whether to enable the alternate screen.

### Request Example
```csharp
w.Up(1).EraseLine(2);          // move up, clear entire line
w.MoveTo(1, 1);               // 1-based cursor position
w.CursorVisible(false);       // ESC[?25l

w.AlternateScreen(true);
// ...
w.AlternateScreen(false);
```

### Response
#### Success Response
- **builder.ToString()** (string) - The accumulated output string.

#### Response Example
```csharp
var s = builder.ToString();
```
```

--------------------------------

### AnsiPalettes.GetBasic16Rgb

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Retrieves the RGB approximation for a basic 16-color palette index. This is useful when rendering colors outside a terminal.

```APIDOC
## AnsiPalettes.GetBasic16Rgb

### Description
Retrieves the RGB approximation for a basic 16-color palette index. This is useful when rendering colors outside a terminal.

### Method
GetBasic16Rgb

### Parameters
- **index** (int) - Required - The palette index (0-15).

### Return Value
- **RGB tuple** - The (R,G,B) approximation for the given index.

### Example
```csharp
var rgb = AnsiPalettes.GetBasic16Rgb(AnsiColors.Red.Index); // (R,G,B) approximation
```
```

--------------------------------

### AnsiWriter Cursor and Erase Methods

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Methods for emitting CSI sequences to control cursor movement, erasing, and scrolling.

```APIDOC
## AnsiWriter Cursor and Erase Methods

### Description
Methods for emitting CSI sequences to control cursor movement, erasing, and scrolling.

### Methods

#### Up(n) / CursorUp(n)
- **Emits**: `ESC[<n>A`
- **Notes**: Cursor up.

#### Down(n) / CursorDown(n)
- **Emits**: `ESC[<n>B`
- **Notes**: Cursor down.

#### Forward(n) / CursorForward(n)
- **Emits**: `ESC[<n>C`
- **Notes**: Cursor forward.

#### Back(n) / CursorBack(n)
- **Emits**: `ESC[<n>D`
- **Notes**: Cursor back.

#### NextLine(n)
- **Emits**: `ESC[<n>E`
- **Notes**: Cursor next line.

#### PreviousLine(n)
- **Emits**: `ESC[<n>F`
- **Notes**: Cursor previous line.

#### CursorHorizontalAbsolute(col)
- **Emits**: `ESC[<col>G`
- **Notes**: 1-based.

#### CursorVerticalAbsolute(row)
- **Emits**: `ESC[<row>d`
- **Notes**: 1-based.

#### MoveTo(row,col) / CursorPosition(row,col)
- **Emits**: `ESC[<row>;<col>H`
- **Notes**: 1-based.

#### HorizontalAndVerticalPosition(row,col)
- **Emits**: `ESC[<row>;<col>f`
- **Notes**: 1-based.

#### EraseLine(mode) / EraseInLine(mode)
- **Emits**: `ESC[<mode>K`
- **Notes**: `mode=0` is emitted as `ESC[K`.

#### EraseDisplay(mode) / EraseInDisplay(mode)
- **Emits**: `ESC[<mode>J`
- **Notes**: `mode=0` is emitted as `ESC[J`.

#### EraseScrollback()
- **Emits**: `ESC[3J`
- **Notes**: Clear scrollback (xterm/Windows Terminal).

#### EraseCharacters(n)
- **Emits**: `ESC[<n>X`
- **Notes**: Erase characters (ECH).

#### InsertCharacters(n)
- **Emits**: `ESC[<n>@`
- **Notes**: Insert characters (ICH).

#### DeleteCharacters(n)
- **Emits**: `ESC[<n>P`
- **Notes**: Delete characters (DCH).

#### InsertLines(n)
- **Emits**: `ESC[<n>L`
- **Notes**: Insert lines (IL).

#### DeleteLines(n)
- **Emits**: `ESC[<n>M`
- **Notes**: Delete lines (DL).

#### ScrollUp(n)
- **Emits**: `ESC[<n>S`
- **Notes**: Scroll up (SU).

#### ScrollDown(n)
- **Emits**: `ESC[<n>T`
- **Notes**: Scroll down (SD).

#### SetScrollRegion(top,bottom)
- **Emits**: `ESC[<top>;<bottom>r`
- **Notes**: DECSTBM.

#### ResetScrollRegion()
- **Emits**: `ESC[r`
- **Notes**: Reset DECSTBM.
```

--------------------------------

### Low-level string controls for terminal graphics

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Writes OSC, DCS, and APC sequences with prepared payloads. These methods only frame payloads; they do not decode or encode image data.

```csharp
w.WriteOsc(1337, "File=inline=1:...base64...".AsSpan());
w.WriteDcs("0;1q...sixel payload...".AsSpan());
w.WriteApc("Gf=100;...base64...".AsSpan());
```

--------------------------------

### AnsiWriter Tab Methods

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Methods for emitting tab-related ANSI sequences.

```APIDOC
## AnsiWriter Tab Methods

### Description
Methods for emitting tab-related ANSI sequences.

### Methods

#### HorizontalTabSet()
- **Emits**: `ESC H`
- **Notes**: HTS.

#### CursorForwardTab(n)
- **Emits**: `ESC[<n>I`
- **Notes**: CHT.

#### CursorBackTab(n)
- **Emits**: `ESC[<n>Z`
- **Notes**: CBT.

#### ClearTabStop()
- **Emits**: `ESC[0g`
- **Notes**: TBC (current column).

#### ClearAllTabStops()
- **Emits**: `ESC[3g`
- **Notes**: TBC (all columns).
```

--------------------------------

### AnsiWriter Simple ESC Sequences

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Methods for emitting simple ESC sequences for keypad modes and line drawing.

```APIDOC
## AnsiWriter Simple ESC Sequences

### Description
Methods for emitting simple ESC sequences for keypad modes and line drawing.

### Methods

#### ReverseIndex()
- **Emits**: `ESC M`
- **Notes**: RI.

#### KeypadApplicationMode()
- **Emits**: `ESC=`
- **Notes**: DECKPAM.

#### KeypadNumericMode()
- **Emits**: `ESC>`
- **Notes**: DECKPNM.

#### EnterLineDrawingMode()
- **Emits**: `ESC(0`
- **Notes**: DEC Special Graphics / line drawing (G0).

#### ExitLineDrawingMode()
- **Emits**: `ESC(B`
- **Notes**: US-ASCII (G0).
```

--------------------------------

### AnsiWriter Cursor Save/Restore Methods

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Methods for saving and restoring cursor position using ESC sequences.

```APIDOC
## AnsiWriter Cursor Save/Restore Methods

### Description
Methods for saving and restoring cursor position using ESC sequences.

### Methods

#### SaveCursor()
- **Emits**: `ESC7`
- **Notes**: DECSC.

#### RestoreCursor()
- **Emits**: `ESC8`
- **Notes**: DECRC.

#### SaveCursorPosition()
- **Emits**: `ESC[s`
- **Notes**: SCOSC.

#### RestoreCursorPosition()
- **Emits**: `ESC[u`
- **Notes**: SCORC.
```

--------------------------------

### Cursor and erase helpers

Source: https://github.com/xenoatom/xenoatom.ansi/blob/main/doc/readme.md

Writes common CSI sequences: move up, erase line, move to 1-based position, and hide cursor (ESC[?25l).

```csharp
w.Up(1).EraseLine(2);          // move up, clear entire line
w.MoveTo(1, 1);               // 1-based cursor position
w.CursorVisible(false);       // ESC[?25l
```
Tokens:
Raw