MarkupString.Ansi 2.27.1

MarkupString.Ansi

Terminal styling for MarkupString: colours (the 16 standard ones, xterm-256 and truecolor), bold/faint/italic/underline/overline/strike/blink/invert, and links — either a URL or a command for the client to send.

One AnsiMarkup layer per span; a run's stack of layers folds into a single SGR sequence for the terminal, one <span> for HTML, or the nearest equivalent in the other formats. Transitions are written as diffs, so nested spans do not restate what is already in effect.

dotnet add package MarkupString.Ansi

Usage

using MarkupString;
using MarkupString.Ansi;
using MarkupString.Html;

MarkupRegistry.Default = MarkupRegistry.Empty.WithAnsi().WithHtml();

var text = MarkupText.Concat(
  MarkupText.Plain("Hello, "),
  MarkupText.Wrap(AnsiCodeParser.Parse("hr"), "world"));

text.Render(MarkupFormat.Ansi);   // Hello, \e[1;31mworld\e[0m
text.Render(MarkupFormat.Html);   // Hello, <span style="color: #ff5555">world</span>

var json = MarkupTextSerializer.Serialize(text);
var back = MarkupTextSerializer.Deserialize(json);

AnsiCodeParser.Parse takes MUSH ansi() syntax — hr, /R, +xterm200, #ff5555, <255 0 0> — and AnsiMarkup.Create(...) builds the same thing from named arguments. AnsiCodeWriter.Write(style) goes the other way, from a style to the codes that produce it.

Formats

WithAnsi() registers emitters for Ansi, Html, Pueblo, Mxp, BBCode and Markdown. Plain needs none: the body passes through. For Markdown it also draws a layout from its tree — a table as a pipe table, lists as lists — so a page made with BlockLayout can be stored in a wiki. See Markdown.

A command link (linkKind: LinkKind.Command) is written in each client's own dialect: <A XCH_CMD> for Pueblo, <SEND HREF> for MXP, an ms-cmd-link anchor carrying xch_cmd for HTML, and the bare text for a terminal. Pueblo and MXP are different dialects, and each client prints the other's tags as text.

An MXP client reads tags only on a line opened in secure mode. The core package's MarkupRegistry.WithMxpSecureLines() opens every line of Mxp output with ESC[1z. Use it on the registry that renders for an MXP connection, and leave it off the one used for tests, logs and previews.

A client that cannot show every colour gets its own registry: MarkupRegistry.Default.WithAnsiOutput(AnsiColorDepth.Xterm256) writes each colour as the nearest one the 256-colour palette has, Standard as the nearest of the sixteen, Attributes with no colour at all, and None with no SGR. It covers Ansi, Pueblo and Mxp. Pass hyperlinks: false for a terminal that prints OSC 8 instead of reading it.

Terminal features: links and pictures

WithAnsiOutput(new AnsiOutputOptions(depth, features) { Pictures = source }) describes one client fully. TerminalFeatures says what its terminal reads beyond colour:

Pictures are drawn into the cells a Figure reserves when it is laid out for such a reader (LayoutContext.Pictures, which answers the cells a picture takes). Each row is marked with the figure's ImageMarkup, its Row saying which row of the picture it is, over the figure's text art, so a box, a flex row or a table around it lines up whichever way it ends up drawn. The pixels come from the host's ITerminalPictureSource: this package neither fetches nor decodes a file. Without the pixels, or without the feature, the row is its art.

• Kitty sends the picture once per connection (a=T,U=1, a PNG in 4096-byte chunks, q=2 so nothing comes back as input) and writes each cell as U+10EEEE with row and column diacritics, the image id as a truecolor foreground. Placeholders are text: they wrap, scroll and are erased like it. MarkTransmitted is how the source says whether the terminal already has it. A moving picture (a TerminalPicture made from TerminalPictureFrames) sends its later frames after the first (a=f,X=1, each with its duration as z), sets the first frame's duration, and starts it looping (a=a,s=3,v=1); the terminal plays it with nothing more sent. Only a client with MovingPictures is sent the frames.
• iTerm2 and sixel are pixels over the screen. A moving picture is sent to iTerm2, given MovingPictures, as a looping GIF. On the picture's first row the cursor makes room below (ESC D per row), comes back up, and draws the picture between ESC 7 and ESC 8; every row then steps over its cells with CSI n C, so no text is written over it. Sixel is the cells' size in pixels (CellWidth × CellHeight, 10 × 20 unless the host knows better; 0, which a terminal reports when it does not know, counts as unknown).
• Half blocks letterbox the picture into two pixels a cell, at the client's colour depth. A client with no colour (Attributes or None) is sent the text art instead.

Each encoding (the PNG, the Kitty transmission, the sixels, the half-block rows) is made once per picture and size and kept with the TerminalPicture, for as long as the host keeps the picture: every other connection shown it at that size is sent a copy. So a host should hand out one TerminalPicture per picture rather than a new one per render.

None of these is sent on a guess: a MUD client that is not a terminal emulator may print them.

Terminals by name

TerminalProfile names the terminals this package knows and what each can be sent. A host identifies the client's terminal from what it reports (TerminalProfile.Identify("kitty(0.35.2)"), a telnet terminal type or an XTVERSION reply) or from the player (TerminalProfile.Find("wezterm")), and sends it only what the player turned on:

var options = AnsiOutputOptions.For(TerminalProfile.WezTerm, chosenByPlayer) with { Pictures = source };

Every one draws half blocks. A cell is empty where the terminal lacks the feature or it could not be confirmed: several terminals read Kitty graphics without the Unicode placeholders this package writes (WezTerm, Konsole, Contour, VS Code), Ghostty does not yet animate them in a release, and iTerm2's own Kitty support is unannounced, so it is drawn for with its own protocol. Windows Terminal and Alacritty do not answer XTVERSION, so only a player can name them.

Reading terminal output

DecoderRegistry.Empty.WithVt().WithPictures() reads SGR, the C0 controls, OSC links, titles and palette, terminal queries, and Kitty, iTerm2 and sixel pictures into MarkupText lines. DisplayRegistry.Core.WithAnsi() resolves them for a web page or a cell grid. See Decoding and Display.

Styling the HTML output

The HTML-family emitters write ms-* classes for the attributes with a fixed rendering (bold, italic, underline, strike, overline, faint, blink, invert, and command links) and inline style for colours, which are open-ended. AnsiCss.Fixed is the stylesheet for those classes — include it once per page, or copy its rules into your own sheet.

Extension points

• IAnsiStyleSource — implement it on your own IMarkup and this package's fold picks the style up, so a layer of yours can contribute bold or a colour without its own emitter per format.
• IMarkupEmitter / IMarkupSetEmitter / IMarkupCodec — replace any of this package's registrations by adding yours to the registry afterwards.

AOT and trimming

IsAotCompatible; no reflection, no dynamic code. Registration is an explicit WithAnsi() call, so nothing depends on a type surviving the trimmer by name.

Licence

Apache-2.0. Source, guides and issues: SharpMUSH/MarkupString.