From d0374a03f348be64971fcfed738f410ecbb881be Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 20:51:51 +0000
Subject: [PATCH 01/19] Add design for decoding wire protocols into MarkupText
 and rendering per output

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rqqt7WGskvSsoRXvKMqybx
---
 .../2026-11-06-display-pipeline-design.md     | 485 ++++++++++++++++++
 1 file changed, 485 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-11-06-display-pipeline-design.md

diff --git a/docs/superpowers/specs/2026-11-06-display-pipeline-design.md b/docs/superpowers/specs/2026-11-06-display-pipeline-design.md
new file mode 100644
index 0000000..37a981e
--- /dev/null
+++ b/docs/superpowers/specs/2026-11-06-display-pipeline-design.md
@@ -0,0 +1,485 @@
+# Display pipeline: decoding wire protocols and rendering them per output — design
+
+Status: draft for review, 2026-11-06. Nothing here is implemented yet.
+
+## Problem
+
+MarkupString renders one way: a `MarkupText` built on the server goes out as ANSI, HTML, MXP, Pueblo and the
+rest. Clients need the opposite direction. They receive a byte stream that mixes text, SGR, OSC, MXP or Pueblo
+tags and entities, and have to turn it into something they can draw: terminal cells, a cell grid drawn by
+Skia, or HTML spans in a browser.
+
+Each SharpMUSH client does this separately today, and none of them uses MarkupString to do it:
+
+| Client | Decode | Model | Draw |
+|---|---|---|---|
+| SharpMUTerm (`SharpMUTerm.Core`) | `AnsiParser`, `MxpParser` (2,260 lines with definitions), `PuebloParser` (786 lines), one per session picked by `ContentFormat` in `WorldSession` | `StyledLine` of `StyledSpan(Text, TextStyle, SpanInteraction?)` | TUI: `MarkupFormatter` turns a line into SharpConsoleUI markup (`[#rrggbb bold link=…]`), resolving colours through the theme and a contrast floor. Window: SharpConsoleUI writes into `CellGrid` (`GridCell(Rune, Combiners, Fg, Bg, Decorations, IsWideContinuation)`), and `CellRenderer` paints it with Skia, drawing Kitty placeholder cells (`U+10EEEE`) as picture slices. |
+| SharpClient (`SharpClient.Core.Rendering`) | `AnsiParser.Parse(line, MxpParserState?)`: SGR, MXP and Pueblo in one 591-line function set | `StyledSegment(Text, TextStyle){Command, Hint, ImageUrl}` | `OutputView.razor`: one `<span style>` per segment from `SegmentStyle.ToCss`, `<button>` for a command, `<img>` for a picture |
+| SharpMUSH portal (`SharpMUSH.Client`) | `TerminalFrameRenderer`: a `markup` frame is a serialized `MarkupText`; a non-envelope frame is plain text with "the legacy ANSI strip" | `MarkupText`, then `TerminalLine(Text, Html)` | `MarkupString` HTML renderer, written into the page as a raw HTML string per line |
+
+The SharpMUTerm source says the cost of this outright: its three escape state machines are "near-copies,
+deliberately not shared — a fix to one belongs in all three, with its own test in each suite". SharpClient has
+a fourth. Each has its own colour type, palette and style record, and each handles a different subset: SharpClient
+reads SGR 0, 1, 4, 7, 22, 24, 27 and colours, so italic, faint and strikethrough are lost; SharpMUTerm reads all of
+them and conceal.
+
+The portal is the exception that shows the way out. It already treats `MarkupText` as its display model, because
+SharpMUSH sends one. A client connected to any other game gets bytes, and needs a decoder that ends in the same
+model.
+
+## Goals
+
+1. One decoder for the wire, shared by all three clients, ending in `MarkupText`.
+2. Protocols as plugins: VT/SGR, OSC 8, MSLP, MXP, Pueblo, raw HTML, each registered on its own, so a client
+   takes only what it supports and a game can add its own.
+3. Renderers as plugins, with three first-class targets: an ANSI terminal, a cell grid, and web spans.
+4. Capability negotiation in both directions: what the client tells the server it can show, and how a renderer
+   degrades what it was sent to what its output can draw.
+5. Keep MarkupString's rules: immutable values, explicit registries, no reflection, Native AOT safe, a layer
+   nobody understands passes its text through.
+
+Non-goals: the telnet layer (option negotiation, MCCP, GMCP, charset). TelnetNegotiationCore owns it; the decoder
+starts after it, on decoded text. Full terminal emulation of full-screen programs is a later, optional tier
+(see [Screen tier](#screen-tier-optional)).
+
+## Prior art and what it settles
+
+| Source | What it settles here |
+|---|---|
+| Paul Williams' DEC ANSI parser state machine, as used by xterm.js (`EscapeSequenceParser`) and Rust `vte` (Alacritty) | Tokenize once with one state machine (ground, escape, CSI, OSC, DCS, SOS/PM/APC strings), and hand complete sequences to handlers. `vte`'s `Perform` trait is the shape: `print`, `execute`, `csi_dispatch`, `esc_dispatch`, `osc_dispatch`, `hook`/`put`/`unhook` for DCS. |
+| xterm.js parser hooks (`registerCsiHandler`, `registerOscHandler`, `registerDcsHandler`, `registerEscHandler`, `registerApcHandler`) | Plugins register by sequence identifier (`{prefix, intermediates, final}` for CSI/DCS, a number for OSC). Handlers are probed newest first; returning `false` passes the sequence on to older handlers, `true` stops. This is the plugin contract for escape sequences. |
+| OSC 8 ([egmontkob's spec](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda)) | `OSC 8 ; params ; URI ST`, closed by `OSC 8 ; ; ST`; params are `:`-separated `key=value`, only `id` defined. Cells with the same URI and non-empty `id` are one link for hover. VTE and iTerm2 cap the URI at 2083 bytes, VTE caps `id` at 250. The cell renderer's link id comes from here. |
+| MXP ([zuggsoft spec](https://www.zuggsoft.com/zmud/mxp.htm)) | Line modes are `ESC [ n z`: 0 open, 1 secure, 2 locked, 3 reset, 4 temp secure, 5–7 lock open/secure/locked, 10–12 room name/description/exits, 19 welcome, 20–99 user-defined. Only formatting tags (B, I, U, S, COLOR, H, FONT) are open; everything else is secure. `<SUPPORT>` is answered `<SUPPORTS +B -IMAGE …>` on a secure line. Line mode is a security boundary, so it belongs inside the MXP plugin, not in the renderer. |
+| Pueblo (as implemented in SharpMUTerm's `PuebloParser` and MarkupString's emitter) | HTML subset; command links are `<A XCH_CMD>`, URL links `<A HREF>`; `<xch_mudtext>` suspends `<BR>` line handling; enabling is a session handshake, not markup. |
+| Kitty graphics Unicode placeholders, and SharpMUTerm's `CellRenderer` | A picture can live in real text cells (`U+10EEEE`, image id in the foreground, row and column in combining marks), so it wraps, scrolls and clips like text. The cell model needs a picture-slice cell for this. |
+| MarkupString's own `TerminalProfile` / `TerminalFeatures` / `AnsiColorDepth` | The degrade ladder for a terminal already exists on the output side: Kitty → iTerm2 inline → sixel → half blocks → text; truecolor → 256 → 16 → attributes → none. Reuse it. |
+
+Lessons from the existing client parsers, which the shared decoder must keep (each is in SharpMUTerm's tests
+already):
+
+- The line boundary is what the host says it is. The telnet layer strips the terminator, so the decoder exposes
+  `EndLine()` and `EndPrompt()` (for GA/EOR) rather than waiting for `\n`.
+- A newline ends any escape sequence in flight. Otherwise a player typing a bare `ESC ]` into a channel swallows
+  the rest of the session.
+- Every buffer is capped: sequence, tag, entity, OSC payload.
+- When MXP leaves open mode, tags opened in open mode are closed. Otherwise `<COLOR FORE=black BACK=black>` in a
+  channel paints the rest of the session.
+- A secure MXP tag on an open line is literal text, so a player cannot make a `<SEND>` in someone else's client.
+- A stray `<` or `&` that cannot start a tag or entity is text.
+
+## Architecture
+
+```text
+            host (telnet layer, websocket)
+                      │  decoded text chunks, EndLine / EndPrompt, mode events (Pueblo on, MXP on)
+                      ▼
+ ┌──────────────── Decoder (one per connection) ─────────────────┐
+ │  VtTokenizer ──► sequence handlers (CSI / OSC / ESC / DCS / APC) │
+ │       │ ground text                                             │
+ │       ▼                                                         │
+ │  TagTokenizer (only while an SGML protocol is active)           │
+ │       └──► tag/entity handlers (MXP, Pueblo, HTML)              │
+ │                         │ act on                                │
+ │                  DecodeState: style, element stack, line mode   │
+ │                         ▼                                       │
+ │                  LineBuilder ──► DisplayLine(MarkupText, kind)  │
+ └──────────────────────────┬──────────────────────────────────────┘
+                            │ DisplayLine stream + DecodeEvents (title, reply-to-server, variables, room, frames)
+                            ▼
+         scrollback, triggers, search, logging   (client-owned, on MarkupText)
+                            │
+            ┌───────────────┼──────────────────┐
+            ▼               ▼                  ▼
+     MarkupFormat.Ansi   CellRenderer       SpanRenderer / MarkupFormat.Html
+     (existing)          → ICellSurface     → DisplaySpan list or HTML string
+```
+
+Three parts, each with its own plugin point:
+
+1. **Decoder**: wire to `MarkupText`. Plugins are protocol handlers.
+2. **Display model**: `MarkupText` with the existing shared vocabulary, a few new markup kinds, and a
+   `DisplayLine` envelope.
+3. **Renderers**: model to output. Plugins are style contributors (how a markup kind looks) and renderers (what
+   the output is).
+
+### 1. Decoder
+
+#### Tokenizer
+
+One `VtTokenizer`, a Williams state machine over `ReadOnlySpan<char>`, kept across `Feed` calls so a sequence can
+straddle chunks. It emits tokens and never interprets them:
+
+```csharp
+public interface IVtTokenSink
+{
+    void Print(ReadOnlySpan<char> text);                       // ground text, one run at a time
+    void Execute(char control);                                // C0: BEL, BS, HT, CR, FF …
+    void Csi(in CsiSequence sequence);                         // params (with ':' subparams), prefix, intermediates, final
+    void Esc(in EscSequence sequence);                         // intermediates, final
+    void Osc(int command, ReadOnlySpan<char> payload);
+    void Dcs(in DcsSequence sequence, ReadOnlySpan<char> data); // buffered, capped
+    void Apc(ReadOnlySpan<char> payload);                      // Kitty graphics
+}
+```
+
+Subparameters matter: `38:2::r:g:b` and `4:3` (curly underline) use `:`. SharpMUTerm's `SgrCodes` reads them;
+MarkupString's `AnsiEscapeParser` and SharpClient's parser split on `;` only and drop them.
+
+`AnsiEscapeParser.Parse(string)` keeps its signature and becomes a one-shot decoder with the VT handlers only.
+
+#### Tag tokenizer
+
+MXP, Pueblo and HTML share SGML-ish lexing: `<NAME attr=value attr="quoted">`, `</NAME>`, `<!ELEMENT …>`,
+`&name;`, `&#n;`, `&#xh;`. One `TagTokenizer` runs over ground text while any tag protocol is active, with the
+caps above, and hands `TagToken`s to tag handlers. Which protocol is active is decoder state, switched by the
+host (`EnableProtocol("mxp")` after telnet option 91; Pueblo after its handshake) or by a handler (`ESC [ 6 z`).
+
+#### Handlers (the protocol plugins)
+
+```csharp
+public interface IDecoderPlugin
+{
+    string Name { get; }                                // "vt", "osc8", "mslp", "mxp", "pueblo", "html"
+    void Register(DecoderBuilder builder);              // adds handlers below; called once per registry
+    DecoderCapabilities Capabilities { get; }           // what it can read, for negotiation
+}
+
+public delegate bool CsiHandler(in CsiSequence seq, DecodeContext context);
+public delegate bool OscHandler(ReadOnlySpan<char> payload, DecodeContext context);
+public delegate bool TagHandler(in TagToken tag, DecodeContext context);
+public delegate bool EntityHandler(ReadOnlySpan<char> name, DecodeContext context);
+
+public sealed class DecoderBuilder
+{
+    public DecoderBuilder OnCsi(CsiIdentifier id, CsiHandler handler);   // { Prefix, Intermediates, Final }
+    public DecoderBuilder OnEsc(EscIdentifier id, EscHandler handler);
+    public DecoderBuilder OnOsc(int command, OscHandler handler);
+    public DecoderBuilder OnDcs(CsiIdentifier id, DcsHandler handler);
+    public DecoderBuilder OnApc(ApcHandler handler);
+    public DecoderBuilder OnTag(string protocol, string name, TagHandler handler);
+    public DecoderBuilder OnEntity(string protocol, EntityHandler handler);
+    public DecoderBuilder OnState<T>(Func<T> create) where T : class;    // per-connection state a plugin owns
+}
+```
+
+Dispatch follows xterm.js: handlers for one identifier are tried newest first, `true` stops, `false` falls through.
+An unclaimed sequence is dropped; an unclaimed tag is dropped on a line allowed to use it and literal otherwise
+(the MXP plugin decides which, through its line mode).
+
+`DecodeContext` is what a handler may touch:
+
+```csharp
+public sealed class DecodeContext
+{
+    public ref AnsiStyle Style { get; }                 // the SGR state
+    public T State<T>() where T : class;                // the plugin's own state (MXP line mode, element definitions)
+    public void Open(IMarkup markup);                   // push a layer over text that follows
+    public void Close(IMarkup markup);                  // pop to it (closing anything opened since, as HTML does)
+    public void Point(IPointMarkup point);              // a sound, a bell, a clear
+    public void Text(ReadOnlySpan<char> text);          // text a handler produces (an entity, a literal tag)
+    public void EndLine();
+    public void Raise(DecodeEvent e);                   // out-of-band: see below
+    public IDecodePolicy Policy { get; }                // trust and limits, see Security
+}
+```
+
+`Open`/`Close` produce `MarkupText` layers, so MXP `<COLOR>`, Pueblo `<FONT>` and SGR all end up as the same
+`AnsiMarkup` the server-side code already writes, and the render side needs no protocol knowledge.
+
+`DecodeEvent` covers what is not text: `TitleChanged` (OSC 0/2), `ReplyToServer(string)` (MXP `<SUPPORTS>`,
+`<VERSION>`, a DA/XTVERSION answer), `VariableSet(name, value)` (MXP `<VAR>`, used by gauges), `FrameOpened`,
+`FrameClosed`, `EntityDefined`, `ElementDefined`, `ProtocolChanged`, `PaletteChanged` (OSC 4/10/11),
+`ClipboardRequest` (OSC 52, denied by default). The client decides what to do with each; the decoder never
+writes to the socket.
+
+#### Shipped plugins and where they live
+
+Each protocol package gains a decoder next to its emitter, so a package speaks its protocol both ways:
+
+| Plugin | Package | Reads |
+|---|---|---|
+| `vt` | `MarkupString.Ansi` | SGR in full (including `:` subparams, 8 conceal, 21 double underline, 58/59 underline colour), C0 controls, CSI `J`/`H` as `ClearScreen` points; other CSI dropped (current behaviour) unless the screen tier is on |
+| `osc8` | `MarkupString.Ansi` | hyperlinks, with `id` |
+| `mslp` | `MarkupString.Ansi` | `OSC 68` command links (what `TerminalFeatures.CommandLinks` writes) |
+| `osc-title`, `osc-palette` | `MarkupString.Ansi` | OSC 0/1/2, 4/10/11/104 as events |
+| `kitty`, `iterm-image`, `sixel` | `MarkupString.Ansi` | pictures as `ImageMarkup` with inline data, off by default |
+| `mxp` | `MarkupString.Mxp` | line modes, open/secure tags, `!ELEMENT`, `!ENTITY`, `SEND` (with menus and `PROMPT`), `A`, `IMAGE`, `SOUND`/`MUSIC`, `FRAME`/`DEST`, `VAR`, `GAUGE`, `STAT`, `EXPIRE`, `RELOCATE`, `USER`/`PASSWORD`, room tags, `SUPPORT`/`VERSION` replies |
+| `pueblo` | `MarkupString.Pueblo` | the HTML subset, `XCH_CMD`, `xch_sound`, `xch_pane`, `xch_page clear`, `xch_mudtext` |
+| `html` | `MarkupString.Html` | raw HTML through an `HtmlTagPolicy` (the portal's `wshtml()` frames) |
+
+The MXP plugin should be a port of SharpMUTerm's `MxpParser` and its tests, not a new parser: it is the most
+complete of the four, and its edge cases are the ones listed above. The same goes for `PuebloParser`.
+
+### 2. Display model
+
+`MarkupText` is the display entity. It already has what a display needs: immutable runs with layered markup,
+grapheme-safe slicing, display-cell width, wrapping, JSON that keeps unknown layers, and the shared vocabulary
+(`ImageMarkup`, `SoundMarkup`, `PaneMarkup`, `GaugeMarkup`, `StatusMarkup`, `VariableMarkup`, `ClearScreenMarkup`,
+`ExpireLinksMarkup`, `RelocateMarkup`, `LoginPromptMarkup`, `BellMarkup`). Using it means the portal's path and the
+decoded path end in the same type, and a trigger highlight is one more layer.
+
+Gaps to close in the vocabulary, found by mapping what the client models carry onto it:
+
+| Need | Today | Proposal |
+|---|---|---|
+| MXP `<SEND>` menu (`href="a|b" hint="…|A|B"`), SharpMUTerm's `SendChoice` | `AnsiMarkup` link is one URL or command | `CommandMenuMarkup(IReadOnlyList<CommandChoice>)` in core |
+| `<SEND PROMPT>` (put in the input line, do not send) | none | `LinkKind.Prompt` |
+| OSC 8 `id` | none | `AnsiStyle.LinkId` |
+| Conceal, double/curly underline, underline colour | none | `AnsiStyle.Concealed`, `UnderlineStyle`, `UnderlineColor` |
+| MXP room parts (`ESC[10z`–`12z`, `<RName>`…) used by SharpMUTerm's mapper | none | `RoomPartMarkup(RoomPart)` as an `IDataMarkup`, so it never changes how text looks |
+| MXP custom element `FLAG` (`set hp`) | none | `ElementFlagMarkup(string)` as an `IDataMarkup` |
+| A trigger highlight, SharpMUTerm's `RuleColor` | none | `HighlightMarkup(colour, scope: Text or Line)` |
+| Image size in cells or percent (SharpMUTerm `ImageExtent`) | `ImageMarkup` has pixels | add the unit to `ImageMarkup` |
+
+A line is an envelope around one `MarkupText`:
+
+```csharp
+public sealed record DisplayLine(MarkupText Content, LineKind Kind)   // Output, Prompt, Echo, System
+{
+    public DateTimeOffset Received { get; init; }
+    public string? Destination { get; init; }      // MXP <DEST>, Pueblo xch_pane: which pane it belongs in
+    public long Sequence { get; init; }            // stable id for scrollback and @key in Blazor
+}
+```
+
+Scrollback, search, logging and triggers stay client-owned and work on `Content.ToPlainText()` and slices of it,
+as they do on `StyledLine.Text` today.
+
+### 3. Renderers
+
+`MarkupFormat` renderers write strings. Cells and component spans are not strings, so they need a second, structured
+path that walks the runs once and folds each run's layers into one resolved style.
+
+#### Resolved style and style contributors
+
+```csharp
+public readonly record struct DisplayStyle
+{
+    public DisplayColor Foreground { get; init; }     // already resolved to RGB, or Default
+    public DisplayColor Background { get; init; }
+    public TextAttributes Attributes { get; init; }   // bold, faint, italic, underline kinds, blink, inverse, conceal, strike, overline
+    public DisplayColor UnderlineColor { get; init; }
+    public int InteractionId { get; init; }           // 0 = none; index into the line's interaction table
+    public int PictureId { get; init; }               // 0 = none
+}
+
+public interface IStyleContributor                    // registered per markup type, like an emitter
+{
+    Type MarkupType { get; }
+    void Apply(IMarkup markup, ref StyleBuilder style, in ResolveContext context);
+}
+```
+
+`ResolveContext` carries the output's capabilities and an `IColorResolver`, which is where SharpMUTerm's theme
+lookup and contrast floor (`Contrast.Legible`) plug in, and where SharpClient's phosphor default lives. Today each
+client resolves colours in its own renderer.
+
+`AnsiMarkup`, `HtmlMarkup` (`b`, `i`, `u`, `font color`), the shared vocabulary and `HighlightMarkup` ship
+contributors. A layer with none contributes nothing and its text still comes out, as in the string renderers.
+
+Interactions (links, command menus, prompt links, image links) go into a per-line table so a renderer can hit-test
+without carrying strings in every cell:
+
+```csharp
+public sealed record Interaction(InteractionKind Kind, string Target, string? Hint,
+                                 IReadOnlyList<CommandChoice>? Choices, string? GroupId);
+```
+
+#### Target 1: terminal
+
+The existing `MarkupFormat.Ansi` emitter, unchanged, with `TerminalProfile`, `TerminalFeatures` and
+`WithAnsiOutput(depth)`. SharpMUTerm running inside kitty or Windows Terminal reaches the screen through
+SharpConsoleUI, so its first step is a `MarkupFormat.Custom("sharpconsoleui")` emitter (in SharpMUTerm, or a
+small `MarkupString.SharpConsoleUI` package) that replaces `MarkupFormatter`. It uses the same `IColorResolver`.
+
+#### Target 2: cell grid
+
+New. Lays a `MarkupText` out to a width with the existing wrapping (`TextLayout`, and the internal `LineWrapper`
+behind it) and `DisplayWidth`, and writes cells:
+
+```csharp
+public readonly record struct Cell(
+    string Grapheme,            // whole cluster: base plus combining marks; "" for a wide character's second column
+    DisplayStyle Style,
+    byte Width,                 // 1 or 2; 0 on the continuation
+    PictureSlice Picture);      // (PictureId, Row, Column) when the cell is part of a picture
+
+public interface ICellSurface
+{
+    int Width { get; }
+    void Write(int row, int column, in Cell cell);
+    void EndRow(int row, RowInfo info);          // soft-wrapped or hard break, for copy and reflow
+}
+
+public sealed class CellRenderer
+{
+    public CellLayout Layout(DisplayLine line, int width, in ResolveContext context);   // rows, interactions, pictures
+    public void Draw(CellLayout layout, ICellSurface surface, int firstRow);
+    public Interaction? HitTest(CellLayout layout, int row, int column);
+}
+```
+
+`Grapheme` is a string rather than SharpMUTerm's `Rune` plus `Combiners`, because a ZWJ emoji or a flag is several
+runes and must stay one cell pair. A host that wants runes splits it.
+
+Pictures reuse SharpMUTerm's approach: a picture is laid out as a block of picture cells, so it scrolls and clips
+with text. The host decides how to draw a picture cell: Skia draws the bitmap slice; a real terminal gets the
+Kitty placeholder, sixel, iTerm2 or half blocks, chosen through `TerminalFeatures` as the ANSI emitter does now.
+
+Adapters: SharpMUTerm's `CellGrid` (window), a SharpConsoleUI control that owns its cells (TUI output panes, phase 3),
+or Terminal.Gui.
+
+#### Target 3: web spans
+
+Two forms from the same walk:
+
+- `MarkupFormat.Html` as it is, for the portal, which writes one HTML string per line.
+- `SpanRenderer`, for component UIs that attach handlers (SharpClient's `@onclick`):
+
+```csharp
+public readonly record struct DisplaySpan(string Text, string? CssClass, string? InlineStyle,
+                                          Interaction? Interaction, ImageMarkup? Image, IPointMarkup? Point);
+
+public static IReadOnlyList<DisplaySpan> Spans(this DisplayLine line, in ResolveContext context);
+```
+
+Class names and CSS variables come from `AnsiCss` (`ms-*`), so SharpClient and the portal can share one stylesheet
+and theme. A `MarkupString.Blazor` package with a `<DisplayLineView>` component is optional and would remove
+`OutputView`'s per-segment markup.
+
+### Capability negotiation
+
+Capabilities flow in two directions and meet at one object per connection.
+
+```csharp
+public sealed record OutputCapabilities(
+    AnsiColorDepth Colors,
+    TextAttributes Attributes,         // what it can draw; blink and conceal are often off by choice
+    InteractionKinds Interactions,     // Url, Command, Prompt, Menu; none for a log file
+    PictureKinds Pictures,             // Bitmap, KittyPlaceholder, Sixel, InlineImage, HalfBlock, AltText
+    bool Sound, bool Panes, bool Gauges,
+    UnicodeLevel Unicode);             // Full, NoWide, Ascii (AsciiFold)
+
+public sealed record ClientCapabilities(OutputCapabilities Output, DecoderCapabilities Input, UserChoices Choices)
+{
+    public ClientCapabilities Effective { get; }       // Output ∩ Input ∩ Choices
+    public MttsFlags ToMtts();                         // for TelnetNegotiationCore's TTYPE cycle
+    public string AnswerMxpSupport(IReadOnlyList<string> asked);   // "<SUPPORTS +B +COLOR -IMAGE …>"
+    public string AnswerMxpVersion(string client, string version);
+}
+```
+
+Inbound: the client should only claim what it can both read and show. A cell grid in a terminal without picture
+support answers `-IMAGE` to MXP, so a game that checks sends text instead of a picture nobody will see. This
+generalises SharpMUTerm's `MxpParser.AnswerSupport`, which already refuses to claim a tag its handler ignores.
+`ToMtts` sets ANSI, UTF-8, 256 colours, truecolor, MSLP, screen reader and the rest from the same object.
+
+Outbound: each renderer takes `OutputCapabilities` in its `ResolveContext` and degrades on its own ladder:
+
+| Feature | Ladder |
+|---|---|
+| Colour | truecolor → xterm-256 (redmean nearest, `AnsiColor.NearestXterm`) → 16 → attributes only → none |
+| Picture | bitmap → Kitty placeholder → iTerm2 inline → sixel → half blocks → alt text |
+| Link | clickable with hover group → underlined text → text |
+| Command menu | menu → first choice as a link → text |
+| Wide or emoji text | as is → `AsciiFold` |
+| Sound, pane, gauge | native → text (pane content goes to the main view) → nothing |
+
+The ladders for colour, pictures and Unicode exist in `MarkupString.Ansi` already; this lifts them to a shared
+`OutputCapabilities` so the cell and span renderers use the same rules.
+
+### Registration
+
+Same pattern as `MarkupRegistry`: immutable, explicit, built once, AOT safe.
+
+```csharp
+var decoders = DecoderRegistry.Empty
+    .WithVt()                                // MarkupString.Ansi
+    .WithHyperlinks()
+    .WithMxp(new MxpDecoderOptions { Client = "SharpMUTerm", Version = v })   // MarkupString.Mxp
+    .WithPueblo();                           // MarkupString.Pueblo
+
+var display = DisplayRegistry.Empty
+    .WithAnsiStyles()                        // style contributors for AnsiMarkup
+    .WithSharedVocabulary()
+    .WithHtmlStyles();
+
+// per connection
+var decoder = decoders.CreateDecoder(policy: DecodePolicy.ForGame(world));
+decoder.LineReady += line => scrollback.Add(line);
+decoder.Event += e => session.Handle(e);
+decoder.Feed(chunk);
+decoder.EndPrompt();                         // on GA / EOR
+```
+
+A registry is shared; a `Decoder` holds one connection's state (style, element stack, MXP definitions, line mode)
+and is not thread-safe, like the client parsers it replaces.
+
+### Security
+
+The decoder reads text written by other players. `IDecodePolicy` holds the decisions:
+
+- Trust per source: MXP line modes decide what a line may use. A plugin asks `context.Policy` before turning
+  text into an interaction, a fetch or an event.
+- URLs pass `UrlSafety.IsSafeNavigableUrl` before they become a link or an image.
+- Fetching a picture or sound tells its host the player's address (SharpClient's settings already say so), so
+  `ImageMarkup` from a decoder is inert until the client chooses to fetch it.
+- OSC 52 (clipboard) and title changes are events the client can refuse; clipboard writes are refused by default.
+- Caps on every buffer, the element stack, entity expansion depth and the number of MXP definitions.
+- Raw HTML only through `HtmlTagPolicy`.
+
+### Screen tier (optional)
+
+MUDs mostly use SGR, but some send cursor addressing for a status area (`DECSTBM` scroll regions, `CUP`, `EL`), and
+MOO editors and door games want a real screen. All three clients drop non-SGR CSI today. A later `vt-screen` plugin
+can claim those sequences and drive a `ScreenBuffer` of `Cell`s instead of the line builder, with the line flow
+continuing below the scroll region. It stays opt-in per world, because a stray cursor move from a game that
+assumes 80×24 is worse in a reflowing pane than dropping it.
+
+## Testing
+
+- Round trip: for every format with an emitter, `Decode(Render(x, f)) ≈ x` as a property over generated
+  `MarkupText` (an extension of `RoundTripProperties`). This tests the decoder and the emitters against each other.
+- Port the client suites: SharpMUTerm's `AnsiParser`, `MxpParser` and `PuebloParser` tests and SharpClient's
+  parser tests become decoder tests, so nothing they pin is lost.
+- Chunking: every test case fed whole and split at every index gives the same lines.
+- Fuzzing: random bytes never throw, never exceed caps, and never leave state that swallows the next line.
+- Captured transcripts from PennMUSH, TinyMUX, an MXP game and a Pueblo game, checked as approved snapshots of cells
+  and spans.
+- Renderer parity: the same `DisplayLine` drawn as cells and as spans gives the same text, styles and interaction
+  ranges, in the spirit of SharpMUTerm's cell-for-cell comparison of its two front ends.
+
+## Migration
+
+| Phase | MarkupString | SharpMUTerm | SharpClient | Portal |
+|---|---|---|---|---|
+| 1 | Tokenizer, `vt`, `osc8`, `mslp` decoders; `DisplayLine`; vocabulary gaps; `AnsiEscapeParser` on the new tokenizer | `ILineParser` adapter over the decoder that still yields `StyledLine`, behind a setting | — | Plain-text frames decoded instead of ANSI-stripped |
+| 2 | `mxp`, `pueblo` decoders (ported), `ClientCapabilities` | Switch to the adapter; delete the three parsers | Replace `AnsiParser`/`MxpParserState` with the decoder | — |
+| 3 | `DisplayStyle`, contributors, `SpanRenderer`, `CellRenderer` | `sharpconsoleui` emitter replaces `MarkupFormatter`; window output panes on `CellRenderer` | `OutputView` on `SpanRenderer` | Optionally the same `SpanRenderer` |
+| 4 | `vt-screen` | Opt-in per world | — | — |
+
+Phase 1 changes nothing a client sees and can ship on its own.
+
+## Package shape
+
+| Package | Adds |
+|---|---|
+| `MarkupString` | Decoder abstractions, `VtTokenizer`, `TagTokenizer`, `DisplayLine`, `DisplayStyle`, `IStyleContributor`, `OutputCapabilities`, `CellRenderer`, `SpanRenderer`, new vocabulary records |
+| `MarkupString.Ansi` | `vt`, `osc8`, `mslp`, title, palette, picture decoders; `AnsiMarkup` style contributor |
+| `MarkupString.Mxp` | `mxp` decoder, `<SUPPORTS>`/`<VERSION>` answers |
+| `MarkupString.Pueblo` | `pueblo` decoder |
+| `MarkupString.Html` | `html` decoder through `HtmlTagPolicy`; `HtmlMarkup` style contributor |
+| `MarkupString.Blazor` (optional) | `<DisplayLineView>` |
+
+The alternative is one new `MarkupString.Display` package holding the decoders and renderers. It keeps the
+existing packages untouched, but splits each protocol across two packages and makes `WithMxp()` mean only half of
+MXP. The table above is the recommendation.
+
+## Open questions
+
+1. Is the screen tier in scope for the first version, or only lines?
+2. Should the SharpConsoleUI emitter live in SharpMUTerm or in a MarkupString package?
+3. Is porting SharpMUTerm's MXP and Pueblo parsers into MarkupString acceptable, given SharpMUTerm is MIT and
+   MarkupString is Apache-2.0? Both are permissive and have the same owners, but the notice has to come along.
+4. Should `CellRenderer` and `SpanRenderer` sit in core, or does core stay free of any renderer and take them in
+   a new package?

From 752f7def7c0b9db25d11f040ce77910d56e1c31d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 21:02:19 +0000
Subject: [PATCH 02/19] Plan each source-to-target conversion for the display
 pipeline, pictures first

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rqqt7WGskvSsoRXvKMqybx
---
 .../plans/2026-11-06-display-pipeline.md      | 451 ++++++++++++++++++
 .../2026-11-06-display-pipeline-design.md     |   5 +
 2 files changed, 456 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-11-06-display-pipeline.md

diff --git a/docs/superpowers/plans/2026-11-06-display-pipeline.md b/docs/superpowers/plans/2026-11-06-display-pipeline.md
new file mode 100644
index 0000000..ddf97f7
--- /dev/null
+++ b/docs/superpowers/plans/2026-11-06-display-pipeline.md
@@ -0,0 +1,451 @@
+# Display pipeline: conversion plan
+
+**Goal:** Every protocol a game sends (ANSI and its extensions first, then MXP and Pueblo) reaches every output a
+SharpMUSH client draws on (an outer terminal, a cell grid, web components, an HTML string) as the best thing that
+output can show, through one decoder and one model.
+
+**Spec:** `docs/superpowers/specs/2026-11-06-display-pipeline-design.md`. This plan works out the conversions the spec
+leaves open, in particular pictures, and orders the work.
+
+**Status:** draft for review, 2026-11-06.
+
+## 1. The rule: decode, never pass through
+
+The tempting shortcut for "Kitty in, Kitty out" is to copy the sequence to the outer terminal. That breaks:
+
+| Why passthrough fails | Where it shows |
+|---|---|
+| Image ids collide. The server numbers its images; so does the client (SharpMUTerm hands out ids from `0xC00000`, and SharpConsoleUI numbers its own) and so does `TerminalPictureWriter.KittyId`. | A game's image 1 replaces the client's map. |
+| A placement is drawn at the server's idea of the cursor. The client's cursor is in a pane, in a layout, under a header. | The picture lands on the input line or a sidebar. |
+| Scrollback reflows. A pane resized after the picture arrived moves the text but not a placed picture. | Pictures float over the wrong lines. Only Unicode placeholders survive this, because they are text. |
+| The outer terminal is not the one the server was told about. The client advertised its own capabilities; the outer terminal may be a different one, or tmux. | Sixel printed as garbage in Alacritty. |
+| `t=f`, `t=t` and `t=s` tell the terminal to read a local file or shared memory object. Passed through, the server reads the player's disk. | Security hole. |
+| Queries (`a=q`, DA1, `CSI 16 t`) are answered by the outer terminal, but its reply arrives on the client's input stream, which SharpConsoleUI owns. | Replies lost, or typed into the command line. |
+
+So every sequence ends at the decoder, becomes model, and each target writes its own output from the model. The
+one optimisation allowed is *encoded passthrough*: a picture that arrived as PNG bytes can be sent to an output
+that takes PNG (Kitty `f=100`, iTerm2, a browser) without decoding the pixels. That reuses the bytes; it never
+reuses the sequence.
+
+```text
+ source sequence ──► decoder plugin ──► model (MarkupText + PictureStore + events) ──► target encoder ──► output
+   Kitty APC          kitty                ImageMarkup{Row} over blank cells             Kitty placeholders
+   sixel DCS          sixel                + PictureAsset(key, pixels | bytes | url)     sixel / iTerm2 / ▀▄
+   MXP <IMAGE>        mxp                                                                Skia bitmap
+   …                                                                                     <img src=blob/data/url>
+```
+
+## 2. Targets
+
+Five targets. They differ in who owns the screen and what they can draw, and a client may use more than one
+(SharpMUTerm has T1 and T3; the portal has T5).
+
+| Id | Target | Example | Owns interaction | Pictures as | Colour |
+|---|---|---|---|---|---|
+| T1 | Outer terminal, client owns the screen | SharpMUTerm TUI inside kitty, Windows Terminal | client (mouse reporting) | Kitty placeholders, iTerm2 inline, sixel, half blocks, chosen by `TerminalProfile` | by profile |
+| T2 | Dumb ANSI sink | a log file, `cat` of a capture, a proxy to a telnet user | the terminal, if anything | as T1 but only what that terminal reads, usually none | `AnsiColorDepth` |
+| T3 | Cell grid drawn by the client | SharpMUTerm window (`CellGrid` + Skia) | client (hit test) | bitmap slices in cells | truecolor |
+| T4 | Web components | SharpClient `OutputView` | client (`@onclick`) | `<img>` from URL, blob or data URI | truecolor via CSS |
+| T5 | HTML string | SharpMUSH portal `TerminalLine.Html` | page script (`xch_cmd`) | `<img>` as T4 | truecolor via CSS |
+
+T2 is MarkupString's existing `MarkupFormat.Ansi` output and needs nothing new beyond the picture source.
+
+## 3. Conversion tables
+
+Each cell says what the target receives. "Text" means the fallback text the decoder kept under the markup: alt
+text for a picture, the label for a link. Nothing in a cell is ever dropped without leaving its text.
+
+### 3.1 Pictures
+
+| Source | T1 Kitty | T1 iTerm2 / sixel | T1 blocks only | T2 | T3 | T4 / T5 |
+|---|---|---|---|---|---|---|
+| Kitty transmit and display (`a=T`, direct `t=d`, `f=24/32/100`, `o=z`, chunked `m=1`) | placeholders, retransmitted once under the client's id | encoded by `TerminalPictureWriter` | half blocks | as T1 for its profile | bitmap | PNG (encoded passthrough for `f=100`, `PngWriter` for raw) |
+| Kitty transmit (`a=t`) then put (`a=p`, `i`/`p`, `c`/`r`) | as above, at the put | as above | as above | as above | as above | as above |
+| Kitty virtual placement (`U=1`) plus `U+10EEEE` placeholder text | placeholder cells re-keyed to the client's id; the picture is already text-shaped | the same rows, drawn | half blocks | as T1 | bitmap slices | `<img>` over the rows' box; a cropped placement is a CSS `object-position` crop |
+| Kitty animation (`a=f` frames, `a=a`) | frames, if `MovingPictures` | iTerm2 GIF if `MovingPictures`; else first frame | first frame | as T1 | frames (host animates) | animated GIF via `GifWriter`, or first frame |
+| Kitty delete (`a=d`, lower or upper case) | see [3.1.3](#313-delete-and-replace) | | | | | |
+| Kitty query (`a=q`) | answered per [section 5](#5-what-the-client-answers) | | | | | |
+| Kitty `t=f`, `t=t`, `t=s` | refused with an error reply; nothing read | | | | | |
+| Sixel (`DCS P1;P2;P3 q … ST`) | decoded to pixels, then as Kitty direct | iTerm2 PNG, or sixel re-encoded at the client's size and palette | half blocks | as T1 | bitmap | PNG |
+| iTerm2 inline (`OSC 1337 ; File=inline=1;… : base64`, single or `MultipartFile`/`FilePart`/`FileEnd`) | Kitty `f=100` when PNG, else decoded | iTerm2: original bytes; sixel: decoded | half blocks | as T1 | bitmap (host decodes) | original bytes as blob or data URI, when the browser reads the type |
+| iTerm2 download (`inline=0`) | never saved; `DownloadOffered` event with name and size, text "[file: name]" | | | | | |
+| MXP `<IMAGE>` (URL + FName, `W`/`H` in px, `c` or `%`, `ALIGN`) | fetched by the host, decoded, then as Kitty direct | as left | half blocks | text | bitmap | `<img src>` with the address itself, after `UrlSafety`; no fetch by the client code |
+| Pueblo / HTML `<img src>` | as MXP | as MXP | as MXP | text | bitmap | as MXP |
+| Half-block, quadrant, sextant or braille art (plain text) | text | text | text | text | text; T3 draws block elements as shapes, as `CellRenderer` already does | text in a monospace span |
+
+Text art is never upgraded to a picture. It is text the server chose; its colours go through the colour table.
+
+#### 3.1.1 Where a picture sits in a line model
+
+All five targets are line-oriented scrollback, not a fixed screen. A picture placed at the cursor becomes rows of
+blank cells under `ImageMarkup { Row = PictureRow(i, rows, columns) }`, which is how MarkupString's `Figure` already
+reserves space, so every target that can draw it draws it and every other one shows the cells' text.
+
+| Source placement | Becomes |
+|---|---|
+| Cursor at the start of a line, picture `r` rows tall | `r` lines, each `columns` blank cells under the picture's row `i` |
+| Cursor mid-line at column `x` (Kitty `C=0`: the spec moves the cursor right by `c` and down by `r`) | the text before it ends its line; then the `r` rows; the cursor is then column `x + c` of a new line below them, so text that follows starts there after blank cells, and a line with nothing written stays empty, as it would on kitty's screen |
+| Kitty `C=1` (cursor does not move) | as above, but on kitty the text that follows overprints the picture; a line model cannot overprint, so it goes below the picture and the line gets an `Overlapped` flag |
+| Sixel (cursor ends on the line below the picture, or to its right with private mode 8452) | below: a new line at column 0. Right of the last row (8452): text there would sit beside the picture, which the line model cannot hold, so it also starts a new line, with the `Overlapped` flag |
+| Unicode placeholders | already cells: each run of `U+10EEEE` becomes blanks under `ImageMarkup.Row`, with its row and starting column read from the diacritics |
+| MXP / Pueblo image in running text | as "cursor mid-line"; an image with no size until fetched is a one-row label (its alt text) until the host has the size, then a `PictureSized` event lets the client re-lay that line |
+
+The last row is what SharpMUTerm already does with `InlineImageHost` (rows inserted under the line once the
+picture is fetched); the plan moves that logic into the shared picture service.
+
+`PictureRow` needs one new field for placeholders that show part of a picture: `FirstColumn`, the column of the
+picture the run starts at (Kitty lets a placement be cropped, and a run of placeholders can start at any
+column).
+
+#### 3.1.2 Sizing
+
+Cells are what matter in every target but T4/T5, and the source and the target can disagree about how many pixels
+a cell is.
+
+1. A size the source gave in cells (Kitty `c`/`r`, iTerm2 `width=N`, MXP `W=Nc`) is kept: the server laid text
+   out around it.
+2. Else a size in pixels (Kitty `s`/`v` or the image's own, iTerm2 `Npx`, MXP `W=N`) is turned into cells with
+   the *target's* cell metrics.
+3. A percentage (iTerm2 `N%`, MXP `W=N%`) is a share of the pane's columns, or of a row cap for height, as
+   SharpMUTerm's `InlineImageLayout` does.
+4. The result keeps the picture's aspect unless the source said otherwise (iTerm2 `preserveAspectRatio=0`, MXP
+   both `W` and `H`), then shrinks to fit the pane width and a maximum height (SharpMUTerm uses 24 rows).
+
+Cell metrics, per target: T1 asks the outer terminal (`CSI 16 t`) where the host can read the reply, else assumes
+8×16, the 1:2 ratio SharpMUTerm chose because it keeps a square picture square under both Kitty and half blocks.
+T3 takes them from its font. T4/T5 measure one monospace cell in CSS and fall back to 8×16; the picture itself
+is sized in CSS pixels with `max-width: 100%`.
+
+Pixels are never stretched past the source's resolution unless the source asked for a larger box.
+
+#### 3.1.3 Delete and replace
+
+A terminal is one screen; a client has scrollback. Kitty's delete means "take it off the screen", and for a
+history that is ambiguous. The decoder raises `PictureWithdrawn(key, freeData)` and the client chooses:
+
+| Policy | Effect | Default for |
+|---|---|---|
+| `KeepInHistory` | old lines keep the picture; uppercase delete only frees it when the store's byte budget needs the room, after which old lines show their text | all clients |
+| `ReplaceInPlace` | a new picture under the same server id and placement id replaces the old one wherever it is shown | a pane or status area, later |
+| `Remove` | lines that showed it show their text from now on | opt-in |
+
+The store never reuses a key. Retransmitting under the same server id gives a new generation
+(`{connection}/kitty/{id}/{generation}`), so caches and Kitty ids derived from the key cannot show stale pixels.
+
+#### 3.1.4 Decoding and fetching
+
+MarkupString stays free of image libraries. It ships what the terminal protocols need, and the host supplies the
+rest:
+
+| Format | Who decodes | Note |
+|---|---|---|
+| Raw RGB/RGBA (Kitty `f=24/32`), zlib (`o=z`) | MarkupString (`System.IO.Compression`) | inflate is capped at `s × v × bytes-per-pixel` |
+| PNG | MarkupString, new small decoder | Kitty `f=100` is the common case; PNG is fully specified and needs only zlib |
+| GIF | MarkupString, new decoder next to `GifWriter` | for iTerm2 and animation |
+| Sixel | MarkupString, new decoder next to `SixelWriter` | HLS and RGB colour registers, repeat, raster attributes, `P2=1` transparent background |
+| JPEG, WebP, anything else | host `IPictureDecoder` | SharpMUTerm: StbImageSharp plus ImageSharp's WebP module (its `ImageDecoder`); Avalonia: Skia; browser: not needed |
+
+Header sniffing (PNG `IHDR`, GIF logical screen, JPEG `SOF`, WebP `VP8`/`VP8L`/`VP8X`) gives the size without
+decoding, so a line can be laid out at once and the pixels decoded off the parse thread.
+
+Fetching a URL is always the host's (`IPictureFetcher`), because it reveals the player's address and needs the
+rules SharpMUTerm's `WebImageLoader` has: http(s) and `data:` only, an image content type, a byte cap, a timeout,
+two concurrent fetches, a queue cap.
+
+#### 3.1.5 The picture store
+
+```csharp
+public sealed class PictureAsset
+{
+    public string Key { get; }                         // never reused
+    public PictureOrigin Origin { get; }               // Inline (bytes arrived in band) or Address (a URL)
+    public string? Address { get; }
+    public PictureSize? NaturalSize { get; }           // pixels, from the header or the source
+    public PictureState State { get; }                 // Declared, Received, Decoded, Failed, Released
+}
+
+public interface IPictureStore : ITerminalPictureSource // so the existing ANSI writers draw from it unchanged
+{
+    PictureAsset Declare(PictureDeclaration declaration);
+    bool TryGetEncoded(string key, out ReadOnlyMemory<byte> bytes, out string mediaType);
+    bool TryGetPixels(string key, [NotNullWhen(true)] out TerminalPicture? picture);
+    event Action<PictureAsset>? Changed;               // Decoded, Sized, Released: the client repaints
+}
+```
+
+One store per session, with an LRU byte budget for pixels and one for encoded bytes, and one picture larger than
+the budget used once and not kept, as `InlineImageHost` does. A decoded in-band picture's `ImageMarkup.Source` is
+`picture:{key}`; MarkupString's HTML emitter currently writes `Source` into `src` as is, so it gains an
+`IPictureAddressProvider` option that turns `picture:` keys into a blob URL or a data URI, and refuses to write a
+`picture:` address it cannot resolve.
+
+### 3.2 Colour
+
+| Source | T1 / T2 | T3 | T4 / T5 |
+|---|---|---|---|
+| SGR 30–37, 90–97, 40–47, 100–107 | kept as standard colours, so the outer terminal's own palette shows them | theme palette (`IColorResolver`) | theme palette as CSS variables (`AnsiCss`) |
+| `38;5;n`, `48;5;n` | at the profile's depth (`AnsiStyle.AtDepth`) | resolved through the xterm table | resolved |
+| `38;2;r;g;b` and `38:2::r:g:b` | at the profile's depth (redmean nearest) | as given | as given |
+| SGR 39, 49 (default) | default | the theme's default | the theme's default |
+| OSC 4 (set palette entry), OSC 104 (reset) | the connection's palette override; standard colours that it redefines are written as RGB so the outer terminal's palette is not changed | override applied in the resolver | override applied |
+| OSC 10/11/12 set default fg/bg/cursor | ignored by default (a player's theme wins), opt-in per world | | |
+| Contrast floor | — | `Contrast.Legible` against the plane, as SharpMUTerm's `MarkupFormatter` does today | same function, so all clients agree |
+
+A palette change never touches the outer terminal. That is the server reaching past the client into the player's
+terminal, which the client exists to mediate.
+
+### 3.3 Attributes
+
+| SGR | T1 / T2 | T3 | T4 / T5 |
+|---|---|---|---|
+| 1 bold, 2 faint, 3 italic, 9 strike, 53 overline | as is, if the profile has them | font weight/style, decorations | CSS |
+| 4 underline; `4:2` double, `4:3` curly, `4:4` dotted, `4:5` dashed; 21 double | the kind if the profile has it, else 4 | decoration kind | `text-decoration-style` |
+| 58/59 underline colour | if supported, else dropped | decoration colour | `text-decoration-color` |
+| 5/6 blink | the player's setting (SharpMUTerm "allow blink"), default off | same | `ms-blink` class, off unless the page turns it on |
+| 7 inverse | inverse | colours swapped at resolve time | colours swapped at resolve time |
+| 8 conceal | conceal | foreground drawn as background; text still selectable and searchable | `color: transparent` |
+| 22–29, 55 off codes | as given | | |
+
+### 3.4 Links and commands
+
+| Source | T1 | T2 | T3 | T4 | T5 |
+|---|---|---|---|---|---|
+| OSC 8 URL (with `id`) | client hit test; also OSC 8 to the outer terminal when the profile has `Hyperlinks`, so its own hover and open work | OSC 8 if `Hyperlinks`, else text | interaction in the cell table, grouped by `id` for hover | `<a href>` after `UrlSafety` | `<a href>` |
+| MXP `<A HREF>`, Pueblo `<A HREF>`, HTML `<a>` | as OSC 8 | as OSC 8 | as OSC 8 | as OSC 8 | as OSC 8 |
+| MXP `<SEND>`, Pueblo `XCH_CMD`, MSLP (`OSC 68`) | client hit test sends the command; never written as MSLP to the outer terminal, which would send it nowhere | MSLP if the sink advertised it, else text | interaction | `<button>` | `ms-cmd-link` with `xch_cmd` |
+| MXP `<SEND PROMPT>` | puts the text in the command line | text | interaction | `<button>` that fills the input | as T4 |
+| MXP `<SEND href="a|b">` menu | context menu | first choice, or text | menu | menu | `ms-cmd-menu` with the choices as data |
+| MXP `<EXPIRE>` | links in that group stop being clickable and keep their text | | | | |
+| A command link from an MXP open line | never made: it is literal text (the security rule in the spec) | | | | |
+
+### 3.5 Sound and attention
+
+| Source | T1 | T2 | T3 | T4 / T5 |
+|---|---|---|---|---|
+| BEL | `BellMarkup` point; the client's attention setting decides, and BEL reaches the outer terminal only if the player allows it | BEL | client's setting | `ms-bell` |
+| MXP `<SOUND>`, `<MUSIC>`, Pueblo `xch_sound` | host audio (SharpMUTerm.Audio) through `IPictureFetcher`'s rules for the file | nothing | host audio | `<audio preload="none">` |
+| MSP `!!SOUND(…)` text triggers | not decoded in v1; a later plugin can claim the text | | | |
+
+### 3.6 Screen controls
+
+These decide whether the line model holds. Everything here is decoded, and nothing is forwarded.
+
+| Source | Line model (default) | Screen tier (opt-in, later) |
+|---|---|---|
+| LF | ends the line (the telnet layer usually ended it already) | cursor down |
+| CR without LF | column 0 of the current line; following text overwrites cells, so a progress bar redraws in place | as a terminal |
+| BS | one cell left; next character overwrites (`a BS _` overstrike is not turned into underline) | as a terminal |
+| HT | kept as a tab; renderers expand to 8 with `TextLayout` | tab stops |
+| FF, `CSI 2 J`, `CSI H CSI J` | `ClearScreenMarkup` point; the client decides (the portal already styles `ms-clear`) | clear |
+| `CSI K` (erase in line) | clears the current line from the cursor, in the line builder | as a terminal |
+| Cursor moves `CUU/CUD/CUF/CUB/CUP`, `DECSTBM`, `?1049h` alternate screen | dropped, as all three clients do today; counted in diagnostics | drive a `ScreenBuffer` |
+| `ESC ( 0` / `ESC ) 0` DEC special graphics, `SO`/`SI` | mapped to Unicode box drawing, so old MUD maps draw | same |
+| OSC 0/2 title | `TitleChanged` event; never forwarded | same |
+| OSC 52 clipboard | `ClipboardRequest` event; refused unless the player allows that world | same |
+| DCS/APC/PM/SOS nobody claimed | consumed, capped, dropped | same |
+
+### 3.7 Structure
+
+| Source | Model | Targets |
+|---|---|---|
+| Telnet GA / EOR (from the host) | `DisplayLine.Kind = Prompt` | SharpMUTerm prompt row, portal prompt row |
+| MXP `<FRAME>` / `<DEST>`, Pueblo `xch_pane` | `PaneMarkup` / `DisplayLine.Destination`, `FrameOpened` events | client pane; a target without panes shows the text in the main view |
+| MXP room tags (`ESC [10z`–`12z`, `<RName>`, `<RDesc>`, `<RExits>`) | `RoomPartMarkup` data layer | invisible; read by SharpMUTerm's `MxpRoomSource` |
+| MXP `<VAR>`, `<GAUGE>`, `<STAT>`, `<!ENTITY>` | `VariableMarkup`, `GaugeMarkup`, `StatusMarkup`, `VariableSet` events | client gauges; else text |
+| MXP `<RELOCATE>`, `<USER>`, `<PASSWORD>` | the existing vocabulary points, raised as events | the client asks the player; never automatic |
+
+## 4. Capabilities
+
+```csharp
+public sealed record OutputCapabilities
+{
+    public AnsiColorDepth Colors { get; init; }
+    public TextAttributes Attributes { get; init; }
+    public UnderlineKinds Underlines { get; init; }
+    public InteractionKinds Interactions { get; init; }    // Url, Command, Prompt, Menu
+    public PictureMethods Pictures { get; init; }          // Bitmap, KittyPlaceholders, InlineImage, Sixel, HalfBlocks
+    public bool MovingPictures { get; init; }
+    public bool Sound { get; init; }
+    public bool Panes { get; init; }
+    public UnicodeLevel Unicode { get; init; }             // Full, NoWide, Ascii
+    public CellMetrics? Cell { get; init; }
+
+    public static OutputCapabilities FromTerminal(TerminalProfile profile, TerminalFeatures chosen, AnsiColorDepth depth);
+    public static OutputCapabilities CellGrid { get; }     // T3
+    public static OutputCapabilities Browser { get; }      // T4, T5
+}
+```
+
+`FromTerminal` maps `TerminalFeatures` one to one (`KittyGraphics` → `KittyPlaceholders`, and so on), so the
+terminal knowledge already in `TerminalProfile` is the only place it lives. A client that shows output in two
+places at once (a T1 pane and a T3 window over the same session) negotiates with the server on the union and
+renders each target with its own capabilities; the decoder's output is the same for both.
+
+`Effective = output ∩ what the decoder can read ∩ what the player turned on`. Pictures count as available when the
+output can draw *some* picture method better than text, because the decoder transcodes: a client in Alacritty
+(half blocks only) can still advertise Kitty input, receive a picture and show it as half blocks. Whether
+half blocks are worth asking for is the player's choice (`PictureFloor`: off, half blocks, native only).
+
+## 5. What the client answers
+
+A server learns what to send by asking. The decoder answers as the virtual terminal the client presents, built
+from `Effective`, and sends nothing a host has not turned on.
+
+| Server sends | Answer | Built from |
+|---|---|---|
+| Telnet TTYPE cycle | client name, then a terminal name, then `MTTS n` | `ToMtts`: 1 ANSI, 2 VT100, 4 UTF-8, 8 256 colours, 32 OSC colour palette, 64 screen reader, 256 truecolor, 1024 MSLP, from `Effective`; sent by the telnet layer |
+| MXP `<SUPPORT tags>` | `<SUPPORTS +B +COLOR -IMAGE …>` on a secure line | the MXP plugin's handlers ∩ `Effective` (no `+IMAGE` without pictures) |
+| MXP `<VERSION>` | `<VERSION MXP=1.0 STYLE=… CLIENT=… VERSION=…>` | host strings |
+| Kitty `a=q` (and feature query `e=`) | `OK` for `t=d` with the formats the store decodes; error for `t=f/t/s`; nothing when `q=2`, no `OK` when `q=1` | `Effective.Pictures` and the decoder list |
+| DA1 `CSI c` | `CSI ? 62 ; 22 c`, plus `; 4` when sixel input is on | decoder list |
+| XTVERSION `CSI > q` | `DCS > | ClientName Version ST` | host strings |
+| `CSI 14 t`, `16 t`, `18 t` | text area pixels, cell pixels, rows and columns of the pane | target cell metrics and pane size |
+| `CSI 6 n` (cursor position) | the pane's last row, the current line's column + 1 | line builder |
+| OSC 10/11 `?` | the theme's default foreground/background as `rgb:rrrr/gggg/bbbb` | `IColorResolver` |
+| Pueblo `This world is Pueblo …` | `PUEBLOCLIENT` with the md5, by the telnet layer | host |
+
+Answers leave through `DecodeEvent.ReplyToServer`; the decoder never writes to the socket. Each answer has a
+switch, and the defaults are on for MXP, Kitty and the size queries and off for cursor position, since a server
+that relies on it assumes a full screen.
+
+## 6. Security limits
+
+Defaults, all configurable in `DecodePolicy`:
+
+| Limit | Default | Why |
+|---|---|---|
+| CSI parameters | 32 | `vte`'s limit |
+| OSC payload, other than pictures | 4 KiB | OSC 8 URIs are capped at 2083 bytes by VTE and iTerm2 |
+| One picture, encoded | 16 MiB | a large PNG; iTerm2 caps one sequence at 1 MiB, mintty at about 4.4 MB |
+| One picture, decoded | 4096 × 4096 and 64 MiB of pixels | a zlib or PNG bomb stops at the cap |
+| Chunked transfers open at once | 4 | a server cannot hold memory with half-sent images |
+| Pictures per line | 8 | |
+| MXP element stack, definitions, entity depth | 64, 512, 8 | |
+| Tag, entity, escape sequence | 4096, 32, 128 chars | SharpMUTerm's current caps |
+
+Every limit hit drops the item, keeps its text, and counts it in diagnostics, so a player can tell why a picture
+did not show.
+
+## 7. Work plan
+
+Each task lists what it produces and when it is done. Tests are TUnit in `MarkupString.Tests`; new public API goes
+in `PublicAPI.Unshipped.txt`; each phase ends with a `CHANGELOG.md` entry and a minor version.
+
+### Phase 0: corpus and harness
+
+- **0.1 Capture corpus.** A folder of real sessions as raw text with line and prompt boundaries marked: PennMUSH,
+  TinyMUX, a Diku with MXP, a Pueblo world, a world sending Kitty or sixel (or a synthetic one), and the existing
+  fixtures from SharpMUTerm's and SharpClient's parser tests. Done when each file has a short note of where it came
+  from and what it exercises.
+- **0.2 Snapshot harness.** Feeds a corpus file through a decoder and writes approved snapshots of the decoded
+  lines (as MarkupString JSON), of cells, and of spans. Done when a changed snapshot fails the build.
+- **0.3 Chunking and fuzz harness.** Every case run whole and split at every index; a fuzzer over random bytes and
+  mutated corpus. Done when it runs in CI with a time budget.
+
+### Phase 1: VT decoding (MarkupString, MarkupString.Ansi)
+
+- **1.1 `VtTokenizer`** (Williams state machine, span based, stateful across `Feed`, `:` subparameters, every cap
+  in section 6, newline aborts a sequence). Tests: the state table, chunking, fuzz.
+- **1.2 Decoder core**: `DecoderRegistry`, `DecoderBuilder`, `DecodeContext`, newest-first dispatch with
+  fall-through, `DecodePolicy`, `DecodeEvent`, `DisplayLine`, `LineBuilder` with CR overwrite, BS, `CSI K`, `EndLine`,
+  `EndPrompt`.
+- **1.3 `vt` plugin**: full SGR, C0, DEC special graphics and `SO`/`SI`, clear screen as a point, title and
+  palette events, OSC 52 event.
+- **1.4 `osc8` and `mslp` plugins**, with `AnsiStyle.LinkId`.
+- **1.5 Vocabulary gaps** from the spec (conceal, underline kinds and colour, `LinkKind.Prompt`,
+  `CommandMenuMarkup`, `RoomPartMarkup`, `ElementFlagMarkup`, `HighlightMarkup`), with codecs, emitters where a
+  format has a spelling, and the JSON round trip.
+- **1.6 `AnsiEscapeParser.Parse`** on the decoder, its tests unchanged and passing.
+- **1.7 Round-trip property**: `Decode(Render(x, Ansi)) ≈ x` for generated `MarkupText`.
+
+Done when SharpMUTerm's `AnsiParser` tests and SharpClient's SGR tests, ported, pass against the decoder.
+
+### Phase 2: capabilities and answers
+
+- **2.1 `OutputCapabilities`** with `FromTerminal`, `CellGrid`, `Browser`; `Effective`.
+- **2.2 Answer builders**: `ToMtts`, DA1, XTVERSION, window and cell size, OSC 10/11, cursor position, each behind
+  a switch, raised as `ReplyToServer`.
+
+Done when a table test checks every answer in section 5 for three profiles (kitty, Alacritty, browser).
+
+### Phase 3: structured renderers (MarkupString, MarkupString.Ansi, MarkupString.Html)
+
+- **3.1 `DisplayStyle`, `IStyleContributor`, `IColorResolver`**, contributors for `AnsiMarkup`, `HtmlMarkup` and
+  the vocabulary; palette override from OSC 4.
+- **3.2 `SpanRenderer`** producing `DisplaySpan`s with `ms-*` classes.
+- **3.3 `CellRenderer`** (`Cell`, `ICellSurface`, layout through `TextLayout`, interaction table, hit test).
+- **3.4 Parity test**: one line as cells and as spans gives the same text, style runs and interaction ranges, over
+  the corpus.
+
+### Phase 4: pictures, model and outputs
+
+- **4.1 `PictureAsset`, `IPictureStore`** (budgets, keys, generations, `Changed`), implementing
+  `ITerminalPictureSource`.
+- **4.2 Decoders**: raw, zlib, PNG, GIF, header sniffers; `IPictureDecoder` and `IPictureFetcher` for the host.
+- **4.3 Sizing** (section 3.1.2), ported from `InlineImageLayout` with its tests.
+- **4.4 `PictureRow.FirstColumn`**, and the ANSI picture writers honouring it.
+- **4.5 Target encoders**: encoded passthrough to Kitty `f=100` and iTerm2; `IPictureAddressProvider` in the HTML
+  emitter and `SpanRenderer`; picture cells in `CellRenderer`.
+
+Done when a picture declared by hand reaches T1 (each method), T3, T4 and T5 from the same `MarkupText`, in snapshot
+tests.
+
+### Phase 5: picture protocols in (MarkupString.Ansi)
+
+- **5.1 `kitty` plugin**: actions `t`, `T`, `p`, `q`, `d`; `t=d` only; formats 24, 32, 100; `o=z`; chunking; ids
+  remapped to store keys; replies; placement to rows (section 3.1.1); `PictureWithdrawn`.
+- **5.2 Kitty placeholders in**: read `U+10EEEE` runs (image id from the foreground, third diacritic, placement id
+  from the underline colour, row and column inference), turn them into `ImageMarkup.Row` cells.
+- **5.3 `sixel` plugin**: decoder, placement, DA1 bit.
+- **5.4 `iterm-image` plugin**: single and multipart, units, `inline=0` as `DownloadOffered`.
+- **5.5 Kitty animation**: whole frames (`a=f` without composition) and `a=a` play and loop; anything else shows
+  the first frame.
+
+Done when each source row of table 3.1 has a snapshot test per target column.
+
+### Phase 6: MXP and Pueblo in (MarkupString.Mxp, MarkupString.Pueblo, MarkupString.Html)
+
+- **6.1 `TagTokenizer`** shared by all three.
+- **6.2 `mxp` plugin**, ported from SharpMUTerm's `MxpParser` and `MxpParser.Definitions` with their tests: line
+  modes, open and secure tags, definitions, entities, links and menus, frames, variables, gauges, room tags,
+  `SUPPORT` and `VERSION`, `<IMAGE>` and `<SOUND>` through the picture store and fetcher.
+- **6.3 `pueblo` plugin**, ported from `PuebloParser` with its tests.
+- **6.4 `html` plugin** through `HtmlTagPolicy`.
+- **6.5 Round trip** for `Mxp` and `Pueblo`, as 1.7.
+
+### Phase 7: consumers
+
+Each step is its own PR in that repository, behind a setting until the snapshots match.
+
+- **SharpMUTerm**: an `ILineParser` adapter over the decoder yielding `StyledLine`, swapped in for `AnsiParser`,
+  `MxpParser` and `PuebloParser` in `WorldSession`; then `InlineImageHost` on the picture store; then a SharpConsoleUI
+  emitter replacing `MarkupFormatter`; then window output panes on `CellRenderer`. The three parsers are deleted
+  once the adapter has shipped one release.
+- **SharpClient**: decoder in place of `AnsiParser` and `MxpParserState`; `OutputView` on `SpanRenderer`;
+  triggers on `DisplayLine` plain text.
+- **SharpMUSH portal**: plain-text frames decoded instead of ANSI-stripped; `IPictureAddressProvider` for pictures
+  that arrive in band.
+
+### Phase 8: later
+
+Kitty frame composition, the screen tier, MSP, MXP `ISMAP`, `ReplaceInPlace` panes.
+
+## 8. Risks
+
+| Risk | Mitigation |
+|---|---|
+| Ported MXP behaviour drifts from SharpMUTerm's during the move | port tests first; SharpMUTerm switches by setting and compares snapshots on the corpus before deleting its parser |
+| Kitty id collisions between the client's framework, the client and the writer's hash | a configurable id range on the output side (`KittyIds`), as `InlineImageHost.FirstKittyId` does now |
+| Re-laying a line when a fetched picture's size arrives moves the scrollback under the reader | only lines below the viewport's top are re-laid in place; a line above it keeps its label until scrolled to |
+| Decoding pictures on the parse thread stalls text | sniff on the thread, decode off it; text is never held for a picture |
+| Answering queries makes a server send things the player did not want | every answer is switchable and the picture floor is the player's |
+| Line model cannot show a server that draws a screen | counted in diagnostics; the screen tier is the answer, opt-in |
+
+## 9. Decisions needed
+
+1. Default delete policy: `KeepInHistory` (recommended) or `Remove`.
+2. Whether to answer `CSI 6 n` at all. Recommended off.
+3. Picture floor default: half blocks allowed (recommended, it is what SharpMUTerm does in Alacritty today) or native
+   only.
+4. Whether MarkupString ships the PNG, GIF and sixel decoders (recommended, needed for Kitty `f=100` and sixel
+   with no host library) or leaves all decoding to the host.
diff --git a/docs/superpowers/specs/2026-11-06-display-pipeline-design.md b/docs/superpowers/specs/2026-11-06-display-pipeline-design.md
index 37a981e..1a87d20 100644
--- a/docs/superpowers/specs/2026-11-06-display-pipeline-design.md
+++ b/docs/superpowers/specs/2026-11-06-display-pipeline-design.md
@@ -436,6 +436,11 @@ can claim those sequences and drive a `ScreenBuffer` of `Cell`s instead of the l
 continuing below the scroll region. It stays opt-in per world, because a stray cursor move from a game that
 assumes 80×24 is worse in a reflowing pane than dropping it.
 
+## Conversions and work plan
+
+What each source becomes on each target, including pictures (Kitty, sixel, iTerm2, MXP), and the order of work, are in
+`docs/superpowers/plans/2026-11-06-display-pipeline.md`.
+
 ## Testing
 
 - Round trip: for every format with an emitter, `Decode(Render(x, f)) ≈ x` as a property over generated

From 08f1876d5d9dcef1e0ca201fe1fca43619d6e7a7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 21:15:44 +0000
Subject: [PATCH 03/19] Mark the display pipeline design and plan accepted

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rqqt7WGskvSsoRXvKMqybx
---
 docs/superpowers/plans/2026-11-06-display-pipeline.md        | 2 +-
 docs/superpowers/specs/2026-11-06-display-pipeline-design.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/superpowers/plans/2026-11-06-display-pipeline.md b/docs/superpowers/plans/2026-11-06-display-pipeline.md
index ddf97f7..9b744f8 100644
--- a/docs/superpowers/plans/2026-11-06-display-pipeline.md
+++ b/docs/superpowers/plans/2026-11-06-display-pipeline.md
@@ -7,7 +7,7 @@ output can show, through one decoder and one model.
 **Spec:** `docs/superpowers/specs/2026-11-06-display-pipeline-design.md`. This plan works out the conversions the spec
 leaves open, in particular pictures, and orders the work.
 
-**Status:** draft for review, 2026-11-06.
+**Status:** accepted 2026-11-06.
 
 ## 1. The rule: decode, never pass through
 
diff --git a/docs/superpowers/specs/2026-11-06-display-pipeline-design.md b/docs/superpowers/specs/2026-11-06-display-pipeline-design.md
index 1a87d20..c832cd0 100644
--- a/docs/superpowers/specs/2026-11-06-display-pipeline-design.md
+++ b/docs/superpowers/specs/2026-11-06-display-pipeline-design.md
@@ -1,6 +1,6 @@
 # Display pipeline: decoding wire protocols and rendering them per output — design
 
-Status: draft for review, 2026-11-06. Nothing here is implemented yet.
+Status: accepted 2026-11-06. Nothing here is implemented yet.
 
 ## Problem
 

From e464530de5171bb8b2d131ae54f8f159013838ca Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 21:41:08 +0000
Subject: [PATCH 04/19] Add display styles, span and cell renderers, menu and
 highlight markup

---
 MarkupString/Decoding/DecodeContext.cs     | 345 +++++++++++
 MarkupString/Decoding/DecodeModel.cs       | 208 +++++++
 MarkupString/Decoding/Decoder.cs           | 241 ++++++++
 MarkupString/Decoding/DecoderRegistry.cs   | 229 ++++++++
 MarkupString/Decoding/LineBuilder.cs       | 115 ++++
 MarkupString/Decoding/VtSequences.cs       |  96 ++++
 MarkupString/Decoding/VtTokenizer.cs       | 628 ++++++++++++++++++++
 MarkupString/Display/CellRenderer.cs       | 236 ++++++++
 MarkupString/Display/DisplayRegistry.cs    | 147 +++++
 MarkupString/Display/DisplayStyle.cs       | 162 ++++++
 MarkupString/Display/OutputCapabilities.cs | 223 +++++++
 MarkupString/Display/SpanRenderer.cs       | 146 +++++
 MarkupString/Elements/CommandMenuMarkup.cs |  40 ++
 MarkupString/Elements/ElementCodecs.cs     |  50 +-
 MarkupString/Elements/PictureRow.cs        |   6 +
 MarkupString/PublicAPI.Unshipped.txt       | 638 +++++++++++++++++++++
 16 files changed, 3509 insertions(+), 1 deletion(-)
 create mode 100644 MarkupString/Decoding/DecodeContext.cs
 create mode 100644 MarkupString/Decoding/DecodeModel.cs
 create mode 100644 MarkupString/Decoding/Decoder.cs
 create mode 100644 MarkupString/Decoding/DecoderRegistry.cs
 create mode 100644 MarkupString/Decoding/LineBuilder.cs
 create mode 100644 MarkupString/Decoding/VtSequences.cs
 create mode 100644 MarkupString/Decoding/VtTokenizer.cs
 create mode 100644 MarkupString/Display/CellRenderer.cs
 create mode 100644 MarkupString/Display/DisplayRegistry.cs
 create mode 100644 MarkupString/Display/DisplayStyle.cs
 create mode 100644 MarkupString/Display/OutputCapabilities.cs
 create mode 100644 MarkupString/Display/SpanRenderer.cs
 create mode 100644 MarkupString/Elements/CommandMenuMarkup.cs

diff --git a/MarkupString/Decoding/DecodeContext.cs b/MarkupString/Decoding/DecodeContext.cs
new file mode 100644
index 0000000..da13ab2
--- /dev/null
+++ b/MarkupString/Decoding/DecodeContext.cs
@@ -0,0 +1,345 @@
+namespace MarkupString.Decoding;
+
+/// <summary>
+/// What a handler may do while a <see cref="Decoder"/> reads: write text under the current markup, change that
+/// markup, end lines, place pictures and raise events. One per decoder.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Text is written under a <see cref="MarkupSet"/> built from two things. <em>Pens</em> are named slots that a
+/// protocol sets and replaces, as SGR replaces the current style. <em>Elements</em> are a stack a tag protocol
+/// opens and closes. A pen sits inside every element, so an SGR colour written inside an MXP <c>&lt;COLOR&gt;</c>
+/// wins, as it does in an MXP client.
+/// </para>
+/// </remarks>
+public sealed class DecodeContext
+{
+	private readonly Decoder _decoder;
+	private readonly Dictionary<Type, object> _states = [];
+	private readonly List<(string Slot, IMarkup Markup)> _pens = [];
+	private readonly List<IMarkup> _elements = [];
+	private readonly Dictionary<string, ITextProtocol> _protocols = new(StringComparer.OrdinalIgnoreCase);
+	private MarkupSet? _set;
+	private bool _setValid;
+	private ITextProtocol? _active;
+	private long _sequence;
+
+	internal DecodeContext(Decoder decoder)
+	{
+		_decoder = decoder;
+		Line = new LineBuilder(decoder.Options.MaxLineLength);
+	}
+
+	internal LineBuilder Line { get; }
+
+	internal string? ActiveProtocolName { get; private set; }
+
+	/// <summary>The decoder's options.</summary>
+	public DecoderOptions Options => _decoder.Options;
+
+	/// <summary>Who the client is, as the host last set it.</summary>
+	public ClientIdentity Identity => _decoder.Identity;
+
+	/// <summary>Counts of what was dropped.</summary>
+	public DecodeDiagnostics Diagnostics => _decoder.Diagnostics;
+
+	/// <summary>The pane the lines being read are for, or null for the main output.</summary>
+	public string? Destination { get; set; }
+
+	/// <summary>The column the next character is written at, in cells.</summary>
+	public int Column => Line.Cursor;
+
+	/// <summary>The elements open now, outermost first.</summary>
+	public IReadOnlyList<IMarkup> Elements => _elements;
+
+	/// <summary>
+	/// This decoder's instance of a plugin's own state, made on first use. A plugin keeps its per-connection state
+	/// here, because the plugin itself is shared by every decoder of its registry.
+	/// </summary>
+	public T State<T>() where T : class, new()
+	{
+		if (_states.TryGetValue(typeof(T), out var state)) return (T)state;
+		var made = new T();
+		_states[typeof(T)] = made;
+		return made;
+	}
+
+	/// <summary>Sets pen <paramref name="slot"/> to <paramref name="markup"/>, or clears it with null.</summary>
+	public void SetPen(string slot, IMarkup? markup)
+	{
+		ArgumentNullException.ThrowIfNull(slot);
+		var index = _pens.FindIndex(pen => pen.Slot == slot);
+		if (markup is null)
+		{
+			if (index < 0) return;
+			_pens.RemoveAt(index);
+		}
+		else if (index < 0)
+		{
+			_pens.Add((slot, markup));
+		}
+		else if (Equals(_pens[index].Markup, markup))
+		{
+			return;
+		}
+		else
+		{
+			_pens[index] = (slot, markup);
+		}
+
+		_setValid = false;
+	}
+
+	/// <summary>What pen <paramref name="slot"/> holds, or null.</summary>
+	public IMarkup? Pen(string slot)
+	{
+		foreach (var pen in _pens)
+		{
+			if (pen.Slot == slot) return pen.Markup;
+		}
+
+		return null;
+	}
+
+	/// <summary>Opens <paramref name="markup"/> over the text that follows, until <see cref="Close"/>.</summary>
+	/// <returns>False when <see cref="DecoderOptions.MaxOpenElements"/> are already open; nothing is opened.</returns>
+	public bool Open(IMarkup markup)
+	{
+		ArgumentNullException.ThrowIfNull(markup);
+		if (_elements.Count >= Options.MaxOpenElements)
+		{
+			Diagnostics.LimitsReached++;
+			return false;
+		}
+
+		_elements.Add(markup);
+		_setValid = false;
+		return true;
+	}
+
+	/// <summary>
+	/// Closes <paramref name="markup"/> (the same instance <see cref="Open"/> was given) and every element opened
+	/// after it, as HTML closes elements left open inside one.
+	/// </summary>
+	/// <returns>False when it is not open.</returns>
+	public bool Close(IMarkup markup)
+	{
+		var index = _elements.FindLastIndex(open => ReferenceEquals(open, markup));
+		if (index < 0) return false;
+		_elements.RemoveRange(index, _elements.Count - index);
+		_setValid = false;
+		return true;
+	}
+
+	/// <summary>Closes the elements from <paramref name="count"/> on, leaving the first <paramref name="count"/> open.</summary>
+	public void CloseTo(int count)
+	{
+		if (count < 0) count = 0;
+		if (count >= _elements.Count) return;
+		_elements.RemoveRange(count, _elements.Count - count);
+		_setValid = false;
+	}
+
+	/// <summary>The markup text written now is under, innermost first, or null for none.</summary>
+	public MarkupSet? CurrentMarkup
+	{
+		get
+		{
+			if (_setValid) return _set;
+			if (_pens.Count == 0 && _elements.Count == 0)
+			{
+				_set = null;
+			}
+			else
+			{
+				var layers = new List<IMarkup>(_pens.Count + _elements.Count);
+				for (var i = _pens.Count - 1; i >= 0; i--) layers.Add(_pens[i].Markup);
+				for (var i = _elements.Count - 1; i >= 0; i--) layers.Add(_elements[i]);
+				_set = MarkupSet.Of(layers);
+			}
+
+			_setValid = true;
+			return _set;
+		}
+	}
+
+	/// <summary>
+	/// Writes printable text, passing it to the registry's print filters first (a character set, picture
+	/// placeholders). A text protocol writes its literal text with this.
+	/// </summary>
+	public void Print(ReadOnlySpan<char> text)
+	{
+		if (text.IsEmpty) return;
+		foreach (var filter in _decoder.Registry.PrintFilters)
+		{
+			if (filter(text, this)) return;
+		}
+
+		Write(text);
+	}
+
+	/// <summary>Writes text under the current markup, as it stands.</summary>
+	public void Write(ReadOnlySpan<char> text) => Write(text, null);
+
+	/// <summary>Writes text under the current markup with <paramref name="inner"/> inside it.</summary>
+	public void Write(ReadOnlySpan<char> text, IMarkup? inner)
+	{
+		if (text.IsEmpty) return;
+		var set = CurrentMarkup;
+		if (inner is not null)
+		{
+			if (set is null)
+			{
+				set = MarkupSet.Of(inner);
+			}
+			else
+			{
+				var layers = new IMarkup[set.Count + 1];
+				layers[0] = inner;
+				for (var i = 0; i < set.Count; i++) layers[i + 1] = set[i];
+				set = MarkupSet.Of(layers.AsSpan());
+			}
+		}
+		if (!Line.Write(text.ToString(), set)) Diagnostics.LimitsReached++;
+	}
+
+	/// <summary>Writes already built text at the cursor.</summary>
+	public void Write(MarkupText text)
+	{
+		ArgumentNullException.ThrowIfNull(text);
+		if (text.Length == 0) return;
+		if (!Line.Put(text)) Diagnostics.LimitsReached++;
+	}
+
+	/// <summary>Writes a point: a bell, a sound, a clear. It takes no cells.</summary>
+	public void Point(IPointMarkup point)
+	{
+		ArgumentNullException.ThrowIfNull(point);
+		Line.Put(MarkupText.Point(point));
+	}
+
+	/// <summary>Moves the cursor to column 0 of the current line; what is written next overwrites.</summary>
+	public void CarriageReturn() => Line.Cursor = 0;
+
+	/// <summary>Moves the cursor <paramref name="cells"/> to the left, stopping at column 0.</summary>
+	public void Backspace(int cells = 1) => Line.Cursor = Math.Max(0, Line.Cursor - Math.Max(0, cells));
+
+	/// <summary>Moves the cursor to <paramref name="column"/> of the current line, which is padded with spaces when it is shorter.</summary>
+	public void MoveToColumn(int column) => Line.Cursor = Math.Clamp(column, 0, Options.MaxLineLength);
+
+	/// <summary>Erases from the cursor to the end of the line.</summary>
+	public void EraseToEndOfLine() => Line.EraseFrom(Line.Cursor);
+
+	/// <summary>Erases from the start of the line to the cursor, leaving blanks.</summary>
+	public void EraseToStartOfLine() => Line.EraseTo(Line.Cursor);
+
+	/// <summary>Erases the whole line; the cursor stays where it is.</summary>
+	public void EraseLine()
+	{
+		var cursor = Line.Cursor;
+		Line.EraseFrom(0);
+		Line.Cursor = cursor;
+	}
+
+	/// <summary>Ends the current line.</summary>
+	public void EndLine() => EndLine(LineKind.Output);
+
+	internal void EndLine(LineKind kind)
+	{
+		_active?.EndLine(this);
+		foreach (var handler in _decoder.Registry.LineEndHandlers) handler(this);
+		var content = Line.Take();
+		_decoder.Complete(new DisplayLine(content, kind) { Sequence = _sequence++, Destination = Destination });
+	}
+
+	/// <summary>
+	/// Places a picture <paramref name="rows"/> tall and <paramref name="columns"/> wide at the cursor, as a terminal
+	/// draws one: its first row beside the text already on the line, each further row on a line of its own
+	/// indented to the same column. The cursor then stands below the picture, at its right edge when
+	/// <paramref name="cursorRight"/> (Kitty) or at column 0 (sixel).
+	/// </summary>
+	/// <param name="picture">The picture; each row is written under a copy with its <see cref="ImageMarkup.Row"/> set.</param>
+	/// <param name="rows">Its height in cells.</param>
+	/// <param name="columns">Its width in cells.</param>
+	/// <param name="cursorRight">Where the cursor goes afterwards.</param>
+	/// <param name="firstColumn">The first column of the picture shown, for a cropped placement.</param>
+	public void PlacePicture(ImageMarkup picture, int rows, int columns, bool cursorRight, int firstColumn = 0)
+	{
+		ArgumentNullException.ThrowIfNull(picture);
+		if (rows <= 0 || columns <= 0) return;
+
+		var column = Line.Cursor;
+		var blank = new string(' ', columns);
+		for (var row = 0; row < rows; row++)
+		{
+			if (row > 0) Line.Cursor = column;
+			var cells = picture with { Row = new PictureRow(row, rows, columns) { FirstColumn = firstColumn } };
+			Write(blank, cells);
+			EndLine();
+		}
+
+		Line.Cursor = cursorRight ? column + columns : 0;
+	}
+
+	/// <summary>Raises an event.</summary>
+	public void Raise(DecodeEvent decodeEvent)
+	{
+		ArgumentNullException.ThrowIfNull(decodeEvent);
+		_decoder.Raise(decodeEvent);
+	}
+
+	/// <summary>Raises a <see cref="ReplyEvent"/>: text for the client to send back to the server.</summary>
+	public void Reply(string text)
+	{
+		ArgumentException.ThrowIfNullOrEmpty(text);
+		_decoder.Raise(new ReplyEvent(text));
+	}
+
+	/// <summary>Whether the text protocol named <paramref name="name"/> is reading the text.</summary>
+	public bool IsActive(string name) => ActiveProtocolName is not null && string.Equals(ActiveProtocolName, name, StringComparison.OrdinalIgnoreCase);
+
+	/// <summary>Turns a text protocol on, turning off any other.</summary>
+	public bool EnableProtocol(string name)
+	{
+		ArgumentNullException.ThrowIfNull(name);
+		if (IsActive(name)) return true;
+		if (!_decoder.Registry.TextProtocols.TryGetValue(name, out var create)) return false;
+
+		if (_active is not null) DisableProtocol(ActiveProtocolName!);
+		if (!_protocols.TryGetValue(name, out var protocol)) _protocols[name] = protocol = create();
+		_active = protocol;
+		ActiveProtocolName = name;
+		Raise(new ProtocolEvent(name, true));
+		return true;
+	}
+
+	/// <summary>Turns a text protocol off.</summary>
+	public void DisableProtocol(string name)
+	{
+		if (!IsActive(name)) return;
+		var protocol = _active!;
+		_active = null;
+		ActiveProtocolName = null;
+		protocol.Reset(this);
+		Raise(new ProtocolEvent(name, false));
+	}
+
+	internal void Feed(ReadOnlySpan<char> text)
+	{
+		if (_active is not null) _active.Feed(text, this);
+		else Print(text);
+	}
+
+	internal void ResetAll()
+	{
+		_active?.Reset(this);
+		_active = null;
+		ActiveProtocolName = null;
+		_states.Clear();
+		_pens.Clear();
+		_elements.Clear();
+		_setValid = false;
+		Destination = null;
+		Line.Take();
+	}
+}
diff --git a/MarkupString/Decoding/DecodeModel.cs b/MarkupString/Decoding/DecodeModel.cs
new file mode 100644
index 0000000..013fdb8
--- /dev/null
+++ b/MarkupString/Decoding/DecodeModel.cs
@@ -0,0 +1,208 @@
+using MarkupString.Display;
+
+namespace MarkupString.Decoding;
+
+/// <summary>What a decoded line is.</summary>
+public enum LineKind
+{
+	/// <summary>Output that ended with a line break.</summary>
+	Output,
+
+	/// <summary>A prompt: output the server marked with telnet GA or EOR, or left without a line break.</summary>
+	Prompt,
+}
+
+/// <summary>One decoded line, ready for scrollback.</summary>
+/// <param name="Content">The line's text and markup, without its line break.</param>
+/// <param name="Kind">Whether it is output or a prompt.</param>
+public sealed record DisplayLine(MarkupText Content, LineKind Kind)
+{
+	/// <summary>The line's number within its decoder, from 0, for keying a view of it.</summary>
+	public long Sequence { get; init; }
+
+	/// <summary>The pane the server sent the line to (MXP <c>&lt;DEST&gt;</c>, Pueblo <c>xch_pane</c>), or null for the main output.</summary>
+	public string? Destination { get; init; }
+}
+
+/// <summary>Something a decoder found that is not text to show.</summary>
+public abstract record DecodeEvent;
+
+/// <summary>Text the client should send back to the server: an answer to a query.</summary>
+/// <param name="Text">The answer, exactly as it is to be sent.</param>
+public sealed record ReplyEvent(string Text) : DecodeEvent;
+
+/// <summary>The server set the window or tab title (OSC 0, 1 or 2).</summary>
+/// <param name="Title">The title.</param>
+/// <param name="Icon">Whether it named the icon (OSC 1) rather than, or as well as, the window.</param>
+public sealed record TitleEvent(string Title, bool Icon) : DecodeEvent;
+
+/// <summary>Which colour a <see cref="PaletteEvent"/> changes.</summary>
+public enum PaletteSlot
+{
+	/// <summary>An entry of the 256-colour palette (OSC 4).</summary>
+	Index,
+
+	/// <summary>The default foreground (OSC 10).</summary>
+	Foreground,
+
+	/// <summary>The default background (OSC 11).</summary>
+	Background,
+
+	/// <summary>The cursor (OSC 12).</summary>
+	Cursor,
+}
+
+/// <summary>The server redefined a colour, or reset it (OSC 4, 10, 11, 12, 104, 110, 111, 112).</summary>
+/// <param name="Slot">Which colour.</param>
+/// <param name="Index">The palette entry, for <see cref="PaletteSlot.Index"/>; -1 with a null colour resets every entry.</param>
+/// <param name="Color">The new colour, or null for a reset.</param>
+public sealed record PaletteEvent(PaletteSlot Slot, int Index, RgbColor? Color) : DecodeEvent;
+
+/// <summary>The server asked to write the clipboard (OSC 52). Refuse it unless the player allowed it.</summary>
+/// <param name="Selection">The selection it named, such as <c>c</c> for the clipboard.</param>
+/// <param name="Text">The text, decoded, or null when it asked to read the clipboard instead.</param>
+public sealed record ClipboardEvent(string Selection, string? Text) : DecodeEvent;
+
+/// <summary>The server set a variable (MXP <c>&lt;VAR&gt;</c> or an entity), for gauges and status bars.</summary>
+/// <param name="Name">The variable.</param>
+/// <param name="Value">Its value, or null when it was deleted.</param>
+public sealed record VariableEvent(string Name, string? Value) : DecodeEvent;
+
+/// <summary>The server offered a file to save (iTerm2 <c>inline=0</c>). It is never saved by the decoder.</summary>
+/// <param name="Name">The name it gave, if any.</param>
+/// <param name="Size">Its size in bytes.</param>
+public sealed record DownloadEvent(string? Name, int Size) : DecodeEvent;
+
+/// <summary>A text protocol such as MXP was turned on or off.</summary>
+/// <param name="Name">The protocol.</param>
+/// <param name="Active">Whether it is now on.</param>
+public sealed record ProtocolEvent(string Name, bool Active) : DecodeEvent;
+
+/// <summary>Who the client is, for answering a server that asks, and what its output can show.</summary>
+public sealed record ClientIdentity
+{
+	/// <summary>The client's name, as it answers XTVERSION and MXP <c>&lt;VERSION&gt;</c>.</summary>
+	public string Name { get; init; } = "MarkupString";
+
+	/// <summary>The client's version.</summary>
+	public string Version { get; init; } = "1.0";
+
+	/// <summary>What the output the session is shown on can draw.</summary>
+	public OutputCapabilities Output { get; init; } = OutputCapabilities.PlainText;
+
+	/// <summary>The pane's width in cells.</summary>
+	public int Columns { get; init; } = 80;
+
+	/// <summary>The pane's height in cells.</summary>
+	public int Rows { get; init; } = 24;
+
+	/// <summary>One cell's width in pixels. 8 by 16 keeps a square picture square under both Kitty and half blocks.</summary>
+	public int CellWidth { get; init; } = 8;
+
+	/// <summary>One cell's height in pixels.</summary>
+	public int CellHeight { get; init; } = 16;
+
+	/// <summary>The default foreground, for a server that asks (OSC 10), or null not to say.</summary>
+	public RgbColor? Foreground { get; init; }
+
+	/// <summary>The default background, for a server that asks (OSC 11), or null not to say.</summary>
+	public RgbColor? Background { get; init; }
+
+	/// <summary>Which questions the decoder answers.</summary>
+	public ClientAnswers Answers { get; init; } = ClientAnswers.Default;
+
+	/// <summary>
+	/// The client's MTTS bits (Mud Terminal Type Standard), for the last step of the telnet TTYPE cycle:
+	/// ANSI, VT100, UTF-8, 256 colours, OSC colour palette, truecolor and MSLP from <see cref="Output"/>.
+	/// </summary>
+	/// <param name="screenReader">Whether the player uses a screen reader.</param>
+	/// <param name="tls">Whether the connection is encrypted.</param>
+	public MttsFlags ToMtts(bool screenReader = false, bool tls = false)
+	{
+		var flags = MttsFlags.Utf8 | MttsFlags.Vt100;
+		if (Output.Colors >= ColorLevel.Standard) flags |= MttsFlags.Ansi;
+		if (Output.Colors >= ColorLevel.Xterm256) flags |= MttsFlags.Colors256 | MttsFlags.OscColorPalette;
+		if (Output.Colors >= ColorLevel.TrueColor) flags |= MttsFlags.TrueColor;
+		if ((Output.Interactions & InteractionKinds.Command) != 0) flags |= MttsFlags.Mslp;
+		if (Output.Unicode == UnicodeLevel.Ascii) flags &= ~MttsFlags.Utf8;
+		if (screenReader) flags |= MttsFlags.ScreenReader;
+		if (tls) flags |= MttsFlags.Ssl;
+		return flags;
+	}
+}
+
+/// <summary>The questions a decoder answers. Each one can be turned off.</summary>
+[Flags]
+public enum ClientAnswers
+{
+	/// <summary>None.</summary>
+	None = 0,
+
+	/// <summary>Device attributes (<c>CSI c</c>) and the terminal's name and version (XTVERSION, <c>CSI &gt; q</c>).</summary>
+	Identity = 1,
+
+	/// <summary>The pane's size in cells and pixels (<c>CSI 14 t</c>, <c>16 t</c>, <c>18 t</c>).</summary>
+	Size = 2,
+
+	/// <summary>The default colours (OSC 10, 11 with <c>?</c>).</summary>
+	Colors = 4,
+
+	/// <summary>Picture protocol queries (Kitty <c>a=q</c>).</summary>
+	Pictures = 8,
+
+	/// <summary>
+	/// The cursor's position (<c>CSI 6 n</c>). Off by default: a server that relies on it assumes a full screen,
+	/// which a scrolling pane is not.
+	/// </summary>
+	CursorPosition = 16,
+
+	/// <summary>MXP <c>&lt;SUPPORT&gt;</c> and <c>&lt;VERSION&gt;</c>.</summary>
+	Mxp = 32,
+
+	/// <summary>Everything but the cursor position.</summary>
+	Default = Identity | Size | Colors | Pictures | Mxp,
+}
+
+/// <summary>The Mud Terminal Type Standard's bits.</summary>
+[Flags]
+public enum MttsFlags
+{
+	/// <summary>None.</summary>
+	None = 0,
+
+	/// <summary>ANSI colour.</summary>
+	Ansi = 1,
+
+	/// <summary>VT100 control sequences.</summary>
+	Vt100 = 2,
+
+	/// <summary>UTF-8.</summary>
+	Utf8 = 4,
+
+	/// <summary>The 256-colour palette.</summary>
+	Colors256 = 8,
+
+	/// <summary>Mouse tracking.</summary>
+	MouseTracking = 16,
+
+	/// <summary>Redefining the palette with OSC 4.</summary>
+	OscColorPalette = 32,
+
+	/// <summary>The player uses a screen reader.</summary>
+	ScreenReader = 64,
+
+	/// <summary>The client is a proxy.</summary>
+	Proxy = 128,
+
+	/// <summary>24-bit colour.</summary>
+	TrueColor = 256,
+
+	/// <summary>The Mud New-Environment Standard.</summary>
+	Mnes = 512,
+
+	/// <summary>The Mud Server Link Protocol: command links.</summary>
+	Mslp = 1024,
+
+	/// <summary>The connection is encrypted.</summary>
+	Ssl = 2048,
+}
diff --git a/MarkupString/Decoding/Decoder.cs b/MarkupString/Decoding/Decoder.cs
new file mode 100644
index 0000000..4e2144c
--- /dev/null
+++ b/MarkupString/Decoding/Decoder.cs
@@ -0,0 +1,241 @@
+namespace MarkupString.Decoding;
+
+/// <summary>
+/// Turns one connection's output into <see cref="DisplayLine"/>s. Make one per connection from a
+/// <see cref="DecoderRegistry"/>; it holds the connection's state (the current style, open elements, half-read
+/// sequences) and is not safe to use from two threads at once.
+/// </summary>
+/// <remarks>
+/// <para>
+/// A line ends at a line feed in the text, or when the host says so with <see cref="EndLine"/> (a telnet layer
+/// that strips line terminators) or <see cref="EndPrompt"/> (telnet GA or EOR).
+/// </para>
+/// <para>Things that are not text — a title, an answer to send back — are raised through <see cref="EventRaised"/>.</para>
+/// </remarks>
+public sealed class Decoder
+{
+	private readonly VtTokenizer _tokenizer;
+	private readonly Sink _sink;
+	private readonly List<DisplayLine> _completed = [];
+
+	internal Decoder(DecoderRegistry registry, DecoderOptions options)
+	{
+		Registry = registry;
+		Options = options;
+		Identity = options.Identity;
+		_tokenizer = new VtTokenizer(options.Limits);
+		Context = new DecodeContext(this);
+		_sink = new Sink(this);
+	}
+
+	/// <summary>The registry this decoder was made from.</summary>
+	public DecoderRegistry Registry { get; }
+
+	/// <summary>The options it was made with.</summary>
+	public DecoderOptions Options { get; }
+
+	/// <summary>Who the client is. Set it again when the pane is resized or the player changes a setting.</summary>
+	public ClientIdentity Identity { get; set; }
+
+	/// <summary>Counts of what was dropped, for a diagnostics view.</summary>
+	public DecodeDiagnostics Diagnostics { get; } = new();
+
+	/// <summary>Raised for each event, as it is found.</summary>
+	public event Action<DecodeEvent>? EventRaised;
+
+	/// <summary>The line read so far, not yet ended.</summary>
+	public MarkupText PendingLine => Context.Line.Peek();
+
+	/// <summary>Whether anything has been read into the current line.</summary>
+	public bool HasPendingLine => !Context.Line.IsEmpty;
+
+	/// <summary>The text protocol now reading the text, such as <c>mxp</c>, or null.</summary>
+	public string? ActiveProtocol => Context.ActiveProtocolName;
+
+	internal DecodeContext Context { get; }
+
+	/// <summary>Reads <paramref name="text"/> and returns the lines it completed.</summary>
+	public IReadOnlyList<DisplayLine> Feed(ReadOnlySpan<char> text)
+	{
+		_tokenizer.Feed(text, _sink);
+		return TakeCompleted();
+	}
+
+	/// <summary>Reads <paramref name="text"/> and returns the lines it completed.</summary>
+	public IReadOnlyList<DisplayLine> Feed(string? text) => Feed((text ?? string.Empty).AsSpan());
+
+	/// <summary>Ends the current line, as a line terminator the host removed would have, and returns it.</summary>
+	public DisplayLine EndLine()
+	{
+		_tokenizer.Interrupt(_sink);
+		Context.EndLine();
+		var lines = TakeCompleted();
+		return lines[^1];
+	}
+
+	/// <summary>
+	/// Ends the current line as a prompt (telnet GA or EOR) and returns it, or returns null when nothing was read
+	/// into it.
+	/// </summary>
+	public DisplayLine? EndPrompt()
+	{
+		_tokenizer.Interrupt(_sink);
+		if (Context.Line.IsEmpty) return null;
+		Context.EndLine(LineKind.Prompt);
+		var lines = TakeCompleted();
+		return lines[^1];
+	}
+
+	/// <summary>Turns on a text protocol the registry offers, such as <c>mxp</c> after telnet negotiates it.</summary>
+	/// <returns>False when the registry offers no protocol of that name.</returns>
+	public bool EnableProtocol(string name) => Context.EnableProtocol(name);
+
+	/// <summary>Turns a text protocol off.</summary>
+	public void DisableProtocol(string name) => Context.DisableProtocol(name);
+
+	/// <summary>Forgets everything: style, open elements, half-read sequences and the pending line.</summary>
+	public void Reset()
+	{
+		_tokenizer.Reset();
+		Context.ResetAll();
+		_completed.Clear();
+	}
+
+	/// <summary>Decodes a whole text at once: its lines, the last one included when it has no line break.</summary>
+	public static IReadOnlyList<DisplayLine> DecodeAll(string? text, DecoderRegistry registry, DecoderOptions? options = null)
+	{
+		ArgumentNullException.ThrowIfNull(registry);
+		var decoder = registry.CreateDecoder(options);
+		var lines = new List<DisplayLine>(decoder.Feed(text));
+		if (decoder.HasPendingLine) lines.Add(decoder.EndLine());
+		return lines;
+	}
+
+	internal void Complete(DisplayLine line) => _completed.Add(line);
+
+	internal void Raise(DecodeEvent e) => EventRaised?.Invoke(e);
+
+	private IReadOnlyList<DisplayLine> TakeCompleted()
+	{
+		if (_completed.Count == 0) return [];
+		var lines = _completed.ToArray();
+		_completed.Clear();
+		return lines;
+	}
+
+	/// <summary>Dispatches what the tokenizer finds to the registry's handlers.</summary>
+	private sealed class Sink(Decoder decoder) : IVtTokenSink
+	{
+		private DecodeContext Context => decoder.Context;
+		private DecoderRegistry Registry => decoder.Registry;
+
+		public void Print(ReadOnlySpan<char> text) => Context.Feed(text);
+
+		public void Execute(char control)
+		{
+			if (Registry.Controls.TryGetValue(control, out var handlers))
+			{
+				foreach (var handler in handlers)
+				{
+					if (handler(control, Context)) return;
+				}
+			}
+
+			// A line feed always ends a line, whatever handles the rest of C0.
+			if (control == '\n')
+			{
+				Context.EndLine();
+				return;
+			}
+
+			decoder.Diagnostics.UnhandledControls++;
+		}
+
+		public void Csi(in CsiSequence sequence)
+		{
+			if (Registry.Csi.TryGetValue(new CsiKey(sequence.Prefix, sequence.Intermediates.ToString(), sequence.Final), out var handlers))
+			{
+				foreach (var handler in handlers)
+				{
+					if (handler(sequence, Context)) return;
+				}
+			}
+
+			decoder.Diagnostics.UnhandledSequences++;
+		}
+
+		public void Esc(in EscSequence sequence)
+		{
+			if (Registry.Esc.TryGetValue(new CsiKey('\0', sequence.Intermediates.ToString(), sequence.Final), out var handlers))
+			{
+				foreach (var handler in handlers)
+				{
+					if (handler(sequence, Context)) return;
+				}
+			}
+
+			decoder.Diagnostics.UnhandledSequences++;
+		}
+
+		public void Osc(ReadOnlySpan<char> payload)
+		{
+			var separator = payload.IndexOf(';');
+			var number = separator < 0 ? payload : payload[..separator];
+			var rest = separator < 0 ? [] : payload[(separator + 1)..];
+			if (int.TryParse(number, System.Globalization.NumberStyles.None, System.Globalization.CultureInfo.InvariantCulture, out var command)
+				&& Registry.Osc.TryGetValue(command, out var handlers))
+			{
+				foreach (var handler in handlers)
+				{
+					if (handler(rest, Context)) return;
+				}
+			}
+
+			decoder.Diagnostics.UnhandledSequences++;
+		}
+
+		public void Dcs(in CsiSequence header, ReadOnlySpan<char> data)
+		{
+			if (Registry.Dcs.TryGetValue(new CsiKey(header.Prefix, header.Intermediates.ToString(), header.Final), out var handlers))
+			{
+				foreach (var handler in handlers)
+				{
+					if (handler(header, data, Context)) return;
+				}
+			}
+
+			decoder.Diagnostics.UnhandledSequences++;
+		}
+
+		public void Apc(ReadOnlySpan<char> payload)
+		{
+			foreach (var handler in Registry.Apc)
+			{
+				if (handler(payload, Context)) return;
+			}
+
+			decoder.Diagnostics.UnhandledSequences++;
+		}
+
+		public void Abandoned(VtSequenceKind kind) => decoder.Diagnostics.AbandonedSequences++;
+	}
+}
+
+/// <summary>Counts of what a decoder dropped.</summary>
+public sealed class DecodeDiagnostics
+{
+	/// <summary>Sequences that were malformed, too long, or cut off by a line ending.</summary>
+	public int AbandonedSequences { get; internal set; }
+
+	/// <summary>Well-formed sequences no handler claimed.</summary>
+	public int UnhandledSequences { get; internal set; }
+
+	/// <summary>Control characters no handler claimed.</summary>
+	public int UnhandledControls { get; internal set; }
+
+	/// <summary>Things dropped because a limit was reached: an element stack, a line length, a picture size.</summary>
+	public int LimitsReached { get; internal set; }
+
+	/// <summary>Pictures that could not be decoded.</summary>
+	public int PicturesFailed { get; internal set; }
+}
diff --git a/MarkupString/Decoding/DecoderRegistry.cs b/MarkupString/Decoding/DecoderRegistry.cs
new file mode 100644
index 0000000..80def85
--- /dev/null
+++ b/MarkupString/Decoding/DecoderRegistry.cs
@@ -0,0 +1,229 @@
+using System.Collections.Frozen;
+
+namespace MarkupString.Decoding;
+
+/// <summary>Claims a control sequence. Returns false to let an older handler for the same sequence try.</summary>
+public delegate bool CsiHandler(in CsiSequence sequence, DecodeContext context);
+
+/// <summary>Claims an escape sequence. Returns false to let an older handler try.</summary>
+public delegate bool EscHandler(in EscSequence sequence, DecodeContext context);
+
+/// <summary>Claims an operating system command. <paramref name="payload"/> is what follows its number and <c>;</c>.</summary>
+public delegate bool OscHandler(ReadOnlySpan<char> payload, DecodeContext context);
+
+/// <summary>Claims a device control string.</summary>
+public delegate bool DcsHandler(in CsiSequence header, ReadOnlySpan<char> data, DecodeContext context);
+
+/// <summary>Claims an application program command.</summary>
+public delegate bool ApcHandler(ReadOnlySpan<char> payload, DecodeContext context);
+
+/// <summary>Claims a C0 control character.</summary>
+public delegate bool ControlHandler(char control, DecodeContext context);
+
+/// <summary>
+/// Sees printable text before it is written, and returns true when it wrote the text itself (with
+/// <see cref="DecodeContext.Write(ReadOnlySpan{char})"/>), as a filter that translates a character set does.
+/// </summary>
+public delegate bool PrintFilter(ReadOnlySpan<char> text, DecodeContext context);
+
+/// <summary>
+/// A protocol carried in the text itself, such as MXP or Pueblo: while it is on, every piece of printable text
+/// goes to it, and it writes what is literal text with <see cref="DecodeContext.Print(ReadOnlySpan{char})"/>.
+/// One instance serves one decoder.
+/// </summary>
+public interface ITextProtocol
+{
+	/// <summary>Reads printable text.</summary>
+	void Feed(ReadOnlySpan<char> text, DecodeContext context);
+
+	/// <summary>The line is ending: finish or abandon whatever is half read, and end what lasts only a line.</summary>
+	void EndLine(DecodeContext context);
+
+	/// <summary>The protocol was turned off, or the decoder reset: forget everything.</summary>
+	void Reset(DecodeContext context);
+}
+
+/// <summary>A protocol that adds handlers to a <see cref="DecoderRegistry"/>.</summary>
+public interface IDecoderPlugin
+{
+	/// <summary>The plugin's name, such as <c>vt</c> or <c>mxp</c>.</summary>
+	string Name { get; }
+
+	/// <summary>Adds this plugin's handlers.</summary>
+	void Register(DecoderBuilder builder);
+}
+
+/// <summary>Collects a plugin's handlers. Handlers added later are tried first.</summary>
+public sealed class DecoderBuilder
+{
+	internal readonly Dictionary<CsiKey, List<CsiHandler>> Csi = [];
+	internal readonly Dictionary<CsiKey, List<DcsHandler>> Dcs = [];
+	internal readonly Dictionary<CsiKey, List<EscHandler>> Esc = [];
+	internal readonly Dictionary<int, List<OscHandler>> Osc = [];
+	internal readonly Dictionary<char, List<ControlHandler>> Controls = [];
+	internal readonly List<ApcHandler> Apc = [];
+	internal readonly List<PrintFilter> PrintFilters = [];
+	internal readonly Dictionary<string, Func<ITextProtocol>> TextProtocols = new(StringComparer.OrdinalIgnoreCase);
+	internal readonly List<Action<DecodeContext>> LineEndHandlers = [];
+
+	internal DecoderBuilder()
+	{
+	}
+
+	/// <summary>Handles the control sequence ending in <paramref name="final"/>, with that prefix and those intermediates.</summary>
+	public DecoderBuilder OnCsi(char final, CsiHandler handler, char prefix = '\0', string intermediates = "")
+	{
+		ArgumentNullException.ThrowIfNull(handler);
+		Add(Csi, new CsiKey(prefix, intermediates ?? string.Empty, final), handler);
+		return this;
+	}
+
+	/// <summary>Handles the device control string whose header ends in <paramref name="final"/>.</summary>
+	public DecoderBuilder OnDcs(char final, DcsHandler handler, char prefix = '\0', string intermediates = "")
+	{
+		ArgumentNullException.ThrowIfNull(handler);
+		Add(Dcs, new CsiKey(prefix, intermediates ?? string.Empty, final), handler);
+		return this;
+	}
+
+	/// <summary>Handles the escape sequence ending in <paramref name="final"/> after those intermediates.</summary>
+	public DecoderBuilder OnEsc(char final, EscHandler handler, string intermediates = "")
+	{
+		ArgumentNullException.ThrowIfNull(handler);
+		Add(Esc, new CsiKey('\0', intermediates ?? string.Empty, final), handler);
+		return this;
+	}
+
+	/// <summary>Handles operating system command <paramref name="command"/>.</summary>
+	public DecoderBuilder OnOsc(int command, OscHandler handler)
+	{
+		ArgumentNullException.ThrowIfNull(handler);
+		ArgumentOutOfRangeException.ThrowIfNegative(command);
+		Add(Osc, command, handler);
+		return this;
+	}
+
+	/// <summary>Handles application program commands. Every handler sees each one until one claims it.</summary>
+	public DecoderBuilder OnApc(ApcHandler handler)
+	{
+		ArgumentNullException.ThrowIfNull(handler);
+		Apc.Insert(0, handler);
+		return this;
+	}
+
+	/// <summary>Handles the C0 control <paramref name="control"/>.</summary>
+	public DecoderBuilder OnControl(char control, ControlHandler handler)
+	{
+		ArgumentNullException.ThrowIfNull(handler);
+		Add(Controls, control, handler);
+		return this;
+	}
+
+	/// <summary>Sees printable text before it is written.</summary>
+	public DecoderBuilder OnPrint(PrintFilter filter)
+	{
+		ArgumentNullException.ThrowIfNull(filter);
+		PrintFilters.Insert(0, filter);
+		return this;
+	}
+
+	/// <summary>Is told whenever a line ends, after a text protocol has been.</summary>
+	public DecoderBuilder OnLineEnd(Action<DecodeContext> handler)
+	{
+		ArgumentNullException.ThrowIfNull(handler);
+		LineEndHandlers.Add(handler);
+		return this;
+	}
+
+	/// <summary>Offers a text protocol by name; a decoder makes one instance when it is first turned on.</summary>
+	public DecoderBuilder TextProtocol(string name, Func<ITextProtocol> create)
+	{
+		ArgumentException.ThrowIfNullOrWhiteSpace(name);
+		ArgumentNullException.ThrowIfNull(create);
+		TextProtocols[name] = create;
+		return this;
+	}
+
+	private static void Add<TKey, T>(Dictionary<TKey, List<T>> table, TKey key, T handler) where TKey : notnull
+	{
+		if (!table.TryGetValue(key, out var list)) table[key] = list = [];
+		list.Insert(0, handler);
+	}
+}
+
+internal readonly record struct CsiKey(char Prefix, string Intermediates, char Final);
+
+/// <summary>
+/// The protocols a decoder reads, built once and shared. Each connection makes its own <see cref="Decoder"/> from
+/// it, which holds that connection's state.
+/// </summary>
+public sealed class DecoderRegistry
+{
+	private readonly IDecoderPlugin[] _plugins;
+
+	private DecoderRegistry(IDecoderPlugin[] plugins)
+	{
+		_plugins = plugins;
+		var builder = new DecoderBuilder();
+		foreach (var plugin in plugins) plugin.Register(builder);
+
+		Csi = builder.Csi.ToFrozenDictionary(pair => pair.Key, pair => pair.Value.ToArray());
+		Dcs = builder.Dcs.ToFrozenDictionary(pair => pair.Key, pair => pair.Value.ToArray());
+		Esc = builder.Esc.ToFrozenDictionary(pair => pair.Key, pair => pair.Value.ToArray());
+		Osc = builder.Osc.ToFrozenDictionary(pair => pair.Key, pair => pair.Value.ToArray());
+		Controls = builder.Controls.ToFrozenDictionary(pair => pair.Key, pair => pair.Value.ToArray());
+		Apc = [.. builder.Apc];
+		PrintFilters = [.. builder.PrintFilters];
+		TextProtocols = builder.TextProtocols.ToFrozenDictionary(StringComparer.OrdinalIgnoreCase);
+		LineEndHandlers = [.. builder.LineEndHandlers];
+	}
+
+	/// <summary>A registry that reads nothing: every sequence is dropped and text passes through.</summary>
+	public static DecoderRegistry Empty { get; } = new([]);
+
+	/// <summary>The plugins, in the order they were added.</summary>
+	public IReadOnlyList<IDecoderPlugin> Plugins => _plugins;
+
+	internal FrozenDictionary<CsiKey, CsiHandler[]> Csi { get; }
+	internal FrozenDictionary<CsiKey, DcsHandler[]> Dcs { get; }
+	internal FrozenDictionary<CsiKey, EscHandler[]> Esc { get; }
+	internal FrozenDictionary<int, OscHandler[]> Osc { get; }
+	internal FrozenDictionary<char, ControlHandler[]> Controls { get; }
+	internal ApcHandler[] Apc { get; }
+	internal PrintFilter[] PrintFilters { get; }
+	internal FrozenDictionary<string, Func<ITextProtocol>> TextProtocols { get; }
+	internal Action<DecodeContext>[] LineEndHandlers { get; }
+
+	/// <summary>A registry with <paramref name="plugin"/> added. A plugin of the same name is replaced.</summary>
+	public DecoderRegistry With(IDecoderPlugin plugin)
+	{
+		ArgumentNullException.ThrowIfNull(plugin);
+		var plugins = _plugins.Where(existing => !string.Equals(existing.Name, plugin.Name, StringComparison.OrdinalIgnoreCase)).Append(plugin);
+		return new DecoderRegistry([.. plugins]);
+	}
+
+	/// <summary>Whether a plugin of that name is installed.</summary>
+	public bool Has(string name) => _plugins.Any(plugin => string.Equals(plugin.Name, name, StringComparison.OrdinalIgnoreCase));
+
+	/// <summary>Whether a text protocol of that name is offered.</summary>
+	public bool HasTextProtocol(string name) => TextProtocols.ContainsKey(name);
+
+	/// <summary>A decoder for one connection.</summary>
+	public Decoder CreateDecoder(DecoderOptions? options = null) => new(this, options ?? new DecoderOptions());
+}
+
+/// <summary>Settings for one decoder.</summary>
+public sealed record DecoderOptions
+{
+	/// <summary>How far a control sequence may grow.</summary>
+	public VtLimits Limits { get; init; } = VtLimits.Default;
+
+	/// <summary>Who the client is, for answering a server that asks.</summary>
+	public ClientIdentity Identity { get; init; } = new();
+
+	/// <summary>The most elements a text protocol may have open at once.</summary>
+	public int MaxOpenElements { get; init; } = 64;
+
+	/// <summary>The longest line, in characters; longer lines are broken.</summary>
+	public int MaxLineLength { get; init; } = 64 * 1024;
+}
diff --git a/MarkupString/Decoding/LineBuilder.cs b/MarkupString/Decoding/LineBuilder.cs
new file mode 100644
index 0000000..07a2b90
--- /dev/null
+++ b/MarkupString/Decoding/LineBuilder.cs
@@ -0,0 +1,115 @@
+namespace MarkupString.Decoding;
+
+/// <summary>
+/// The line being read: pieces of text appended at the cursor, and overwritten in place when the cursor has been
+/// moved back (a carriage return, a backspace), so a progress bar redrawn over itself ends as its last state.
+/// </summary>
+internal sealed class LineBuilder(int maxLength)
+{
+	private readonly List<MarkupText> _parts = [];
+	private int _width;
+	private int _length;
+	private int _cursor;
+
+	public bool IsEmpty => _parts.Count == 0;
+
+	/// <summary>The column the next text is written at. Past the end, the gap is filled with spaces when text comes.</summary>
+	public int Cursor
+	{
+		get => _cursor;
+		set => _cursor = Math.Max(0, value);
+	}
+
+	public bool Write(string text, MarkupSet? markups) =>
+		Put(markups is null ? MarkupText.Plain(text) : MarkupText.Wrap(markups, text));
+
+	/// <summary>Writes <paramref name="text"/> at the cursor and moves the cursor past it.</summary>
+	/// <returns>False when the line was full and the text was dropped.</returns>
+	public bool Put(MarkupText text)
+	{
+		if (_length + text.Length > maxLength) return false;
+
+		if (_cursor > _width)
+		{
+			var gap = MarkupText.Plain(new string(' ', _cursor - _width));
+			Append(gap);
+		}
+
+		var width = text.DisplayWidth;
+		if (_cursor == _width)
+		{
+			Append(text);
+			_cursor = _width;
+			return true;
+		}
+
+		// Overwrite the cells from the cursor on.
+		var line = Materialise();
+		var before = line.Substring(0, DisplayWidth.IndexAtWidth(line.Text, _cursor));
+		var after = line.Substring(DisplayWidth.IndexAtWidth(line.Text, _cursor + width));
+		Replace(MarkupText.Concat([before, text, after]));
+		_cursor = before.DisplayWidth + width;
+		return true;
+	}
+
+	/// <summary>Removes everything from column <paramref name="column"/> on.</summary>
+	public void EraseFrom(int column)
+	{
+		if (column >= _width) return;
+		var line = Materialise();
+		Replace(line.Substring(0, DisplayWidth.IndexAtWidth(line.Text, column)));
+	}
+
+	/// <summary>Blanks everything up to and including column <paramref name="column"/>.</summary>
+	public void EraseTo(int column)
+	{
+		if (_width == 0) return;
+		var line = Materialise();
+		var end = Math.Min(_width, column + 1);
+		var after = line.Substring(DisplayWidth.IndexAtWidth(line.Text, end));
+		Replace(MarkupText.Concat(MarkupText.Plain(new string(' ', end)), after));
+	}
+
+	/// <summary>The line as it stands.</summary>
+	public MarkupText Peek() => _parts.Count switch
+	{
+		0 => MarkupText.Empty,
+		1 => _parts[0],
+		_ => Materialise(),
+	};
+
+	/// <summary>The line, which is then empty with the cursor at column 0.</summary>
+	public MarkupText Take()
+	{
+		var line = Peek();
+		_parts.Clear();
+		_width = 0;
+		_length = 0;
+		_cursor = 0;
+		return line;
+	}
+
+	private void Append(MarkupText text)
+	{
+		_parts.Add(text);
+		_width += text.DisplayWidth;
+		_length += text.Length;
+	}
+
+	private MarkupText Materialise()
+	{
+		if (_parts.Count == 1) return _parts[0];
+		var line = MarkupText.Concat(System.Runtime.InteropServices.CollectionsMarshal.AsSpan(_parts));
+		_parts.Clear();
+		_parts.Add(line);
+		return line;
+	}
+
+	private void Replace(MarkupText line)
+	{
+		_parts.Clear();
+		_width = 0;
+		_length = 0;
+		if (line.Length > 0) Append(line);
+	}
+}
diff --git a/MarkupString/Decoding/VtSequences.cs b/MarkupString/Decoding/VtSequences.cs
new file mode 100644
index 0000000..8024ff7
--- /dev/null
+++ b/MarkupString/Decoding/VtSequences.cs
@@ -0,0 +1,96 @@
+namespace MarkupString.Decoding;
+
+/// <summary>What a <see cref="VtTokenizer"/> hands on as it reads.</summary>
+public interface IVtTokenSink
+{
+	/// <summary>Printable text with no controls in it.</summary>
+	void Print(ReadOnlySpan<char> text);
+
+	/// <summary>A C0 control character other than <c>ESC</c>: a line feed, a bell, a backspace.</summary>
+	void Execute(char control);
+
+	/// <summary>A complete control sequence.</summary>
+	void Csi(in CsiSequence sequence);
+
+	/// <summary>A complete escape sequence.</summary>
+	void Esc(in EscSequence sequence);
+
+	/// <summary>An operating system command's payload, the number and its <c>;</c> included.</summary>
+	void Osc(ReadOnlySpan<char> payload);
+
+	/// <summary>A device control string: its header, read as a control sequence, and its data.</summary>
+	void Dcs(in CsiSequence header, ReadOnlySpan<char> data);
+
+	/// <summary>An application program command's payload.</summary>
+	void Apc(ReadOnlySpan<char> payload);
+
+	/// <summary>A sequence that was malformed, too long, or cut off by a line ending.</summary>
+	void Abandoned(VtSequenceKind kind);
+}
+
+/// <summary>
+/// A control sequence: an optional private prefix (<c>&lt;</c> to <c>?</c>), parameters, up to two intermediates,
+/// and a final character. A parameter left empty reads as <see cref="Omitted"/>.
+/// </summary>
+public readonly ref struct CsiSequence
+{
+	/// <summary>The value of a parameter that was left empty.</summary>
+	public const int Omitted = -1;
+
+	private readonly ReadOnlySpan<int> _parameters;
+	private readonly ReadOnlySpan<bool> _subparameters;
+
+	/// <summary>A sequence from its parts.</summary>
+	public CsiSequence(char prefix, ReadOnlySpan<int> parameters, ReadOnlySpan<bool> subparameters, ReadOnlySpan<char> intermediates, char final)
+	{
+		if (parameters.Length != subparameters.Length)
+			throw new ArgumentException("There is one subparameter flag per parameter.", nameof(subparameters));
+		Prefix = prefix;
+		_parameters = parameters;
+		_subparameters = subparameters;
+		Intermediates = intermediates;
+		Final = final;
+	}
+
+	/// <summary>The private prefix, or <c>'\0'</c>.</summary>
+	public char Prefix { get; }
+
+	/// <summary>The intermediate characters, between the parameters and the final character.</summary>
+	public ReadOnlySpan<char> Intermediates { get; }
+
+	/// <summary>The final character, which with the prefix and intermediates names the sequence.</summary>
+	public char Final { get; }
+
+	/// <summary>Every parameter, subparameters included, <see cref="Omitted"/> where empty.</summary>
+	public ReadOnlySpan<int> Parameters => _parameters;
+
+	/// <summary>How many parameters there are, subparameters included.</summary>
+	public int Count => _parameters.Length;
+
+	/// <summary>Parameter <paramref name="index"/>, or <paramref name="fallback"/> when it is missing or empty.</summary>
+	public int Get(int index, int fallback = 0) =>
+		index < _parameters.Length && _parameters[index] != Omitted ? _parameters[index] : fallback;
+
+	/// <summary>Whether parameter <paramref name="index"/> follows a <c>:</c>, making it a subparameter of the one before.</summary>
+	public bool IsSubparameter(int index) => index < _subparameters.Length && _subparameters[index];
+
+	/// <summary>Whether this is the sequence <paramref name="final"/> with <paramref name="prefix"/> and no intermediates.</summary>
+	public bool Is(char final, char prefix = '\0') => Final == final && Prefix == prefix && Intermediates.IsEmpty;
+}
+
+/// <summary>An escape sequence: <c>ESC</c>, up to two intermediates, and a final character.</summary>
+public readonly ref struct EscSequence
+{
+	/// <summary>A sequence from its parts.</summary>
+	public EscSequence(ReadOnlySpan<char> intermediates, char final)
+	{
+		Intermediates = intermediates;
+		Final = final;
+	}
+
+	/// <summary>The intermediate characters, such as the <c>(</c> of <c>ESC ( 0</c>.</summary>
+	public ReadOnlySpan<char> Intermediates { get; }
+
+	/// <summary>The final character.</summary>
+	public char Final { get; }
+}
diff --git a/MarkupString/Decoding/VtTokenizer.cs b/MarkupString/Decoding/VtTokenizer.cs
new file mode 100644
index 0000000..88f652d
--- /dev/null
+++ b/MarkupString/Decoding/VtTokenizer.cs
@@ -0,0 +1,628 @@
+namespace MarkupString.Decoding;
+
+/// <summary>
+/// Splits a stream of text into printable text and terminal control sequences, following the DEC parser state
+/// machine described by Paul Williams (the one xterm.js and Rust's <c>vte</c> implement). It recognises sequences
+/// and never interprets them: what a sequence means is the <see cref="IVtTokenSink"/>'s business.
+/// </summary>
+/// <remarks>
+/// <para>State carries across <see cref="Feed"/> calls, so a sequence may arrive in pieces.</para>
+/// <para>
+/// A line feed ends any sequence in flight. Without that, an unterminated string sequence (a bare <c>ESC ]</c> or
+/// <c>ESC _</c>, which a player can type into a channel) would swallow the rest of a session. Every buffer is
+/// capped by <see cref="VtLimits"/>; a sequence that overflows is consumed to its end and reported abandoned.
+/// </para>
+/// <para>C1 controls (U+0080 to U+009F) are text, as xterm treats them in UTF-8.</para>
+/// </remarks>
+public sealed class VtTokenizer
+{
+	private const char Escape = '\e';
+	private const char Bell = '\a';
+	private const int Omitted = -1;
+
+	private enum State
+	{
+		Ground,
+		Escape,
+		EscapeIntermediate,
+		CsiEntry,
+		CsiParam,
+		CsiIntermediate,
+		CsiIgnore,
+		OscString,
+		DcsEntry,
+		DcsParam,
+		DcsIntermediate,
+		DcsPassthrough,
+		DcsIgnore,
+		ApcString,
+		IgnoredString,
+	}
+
+	private readonly VtLimits _limits;
+	private readonly int[] _parameters;
+	private readonly bool[] _subparameters;
+	private readonly char[] _intermediates = new char[2];
+	private readonly System.Text.StringBuilder _string = new();
+
+	private State _state;
+	private int _parameterCount;
+	private int _intermediateCount;
+	private char _prefix;
+	private bool _parameterStarted;
+	private bool _overflow;
+	private bool _stringEscape;
+	private char _dcsFinal;
+
+	/// <summary>A tokenizer with <see cref="VtLimits.Default"/>.</summary>
+	public VtTokenizer() : this(VtLimits.Default)
+	{
+	}
+
+	/// <summary>A tokenizer with the given limits.</summary>
+	public VtTokenizer(VtLimits limits)
+	{
+		ArgumentNullException.ThrowIfNull(limits);
+		_limits = limits;
+		_parameters = new int[Math.Max(1, limits.MaxParameters)];
+		_subparameters = new bool[_parameters.Length];
+	}
+
+	/// <summary>Whether a sequence has started and not yet ended.</summary>
+	public bool InSequence => _state != State.Ground;
+
+	/// <summary>Reads <paramref name="text"/>, handing what it finds to <paramref name="sink"/> in order.</summary>
+	public void Feed(ReadOnlySpan<char> text, IVtTokenSink sink)
+	{
+		ArgumentNullException.ThrowIfNull(sink);
+
+		var printStart = -1;
+		for (var i = 0; i < text.Length; i++)
+		{
+			var c = text[i];
+
+			if (_state == State.Ground)
+			{
+				if (c >= ' ' && c != '\u007f')
+				{
+					if (printStart < 0) printStart = i;
+					continue;
+				}
+
+				if (printStart >= 0)
+				{
+					sink.Print(text[printStart..i]);
+					printStart = -1;
+				}
+
+				if (c == Escape) EnterEscape();
+				else if (c != '\u007f') sink.Execute(c);
+				continue;
+			}
+
+			Step(c, sink);
+		}
+
+		if (printStart >= 0) sink.Print(text[printStart..]);
+	}
+
+	/// <summary>
+	/// Abandons any sequence in flight, as a line ending does. A host whose telnet layer strips line terminators
+	/// calls this at each line boundary.
+	/// </summary>
+	public void Interrupt(IVtTokenSink sink)
+	{
+		ArgumentNullException.ThrowIfNull(sink);
+		if (_state != State.Ground) Abandon(sink);
+	}
+
+	/// <summary>Forgets any sequence in flight without reporting it.</summary>
+	public void Reset()
+	{
+		_state = State.Ground;
+		_string.Clear();
+	}
+
+	private void Step(char c, IVtTokenSink sink)
+	{
+		// A line feed ends the line whatever is in flight.
+		if (c == '\n')
+		{
+			Abandon(sink);
+			sink.Execute(c);
+			return;
+		}
+
+		// CAN and SUB cancel a sequence everywhere.
+		if (c is '\u0018' or '\u001a')
+		{
+			Abandon(sink);
+			return;
+		}
+
+		switch (_state)
+		{
+			case State.Escape:
+				StepEscape(c, sink);
+				break;
+			case State.EscapeIntermediate:
+				StepEscapeIntermediate(c, sink);
+				break;
+			case State.CsiEntry:
+			case State.CsiParam:
+			case State.CsiIntermediate:
+			case State.CsiIgnore:
+				StepCsi(c, sink);
+				break;
+			case State.OscString:
+				StepOsc(c, sink);
+				break;
+			case State.DcsEntry:
+			case State.DcsParam:
+			case State.DcsIntermediate:
+			case State.DcsIgnore:
+				StepDcsHeader(c, sink);
+				break;
+			case State.DcsPassthrough:
+			case State.ApcString:
+			case State.IgnoredString:
+				StepString(c, sink);
+				break;
+		}
+	}
+
+	private void EnterEscape()
+	{
+		_state = State.Escape;
+		_intermediateCount = 0;
+		_overflow = false;
+	}
+
+	private void StepEscape(char c, IVtTokenSink sink)
+	{
+		switch (c)
+		{
+			case Escape:
+				EnterEscape();
+				return;
+			case '[':
+				EnterParameters(State.CsiEntry);
+				return;
+			case ']':
+				EnterString(State.OscString);
+				return;
+			case 'P':
+				EnterParameters(State.DcsEntry);
+				return;
+			case '_':
+				EnterString(State.ApcString);
+				return;
+			case 'X' or '^':
+				EnterString(State.IgnoredString);
+				return;
+		}
+
+		if (c < ' ')
+		{
+			sink.Execute(c);
+			return;
+		}
+
+		if (c <= '/')
+		{
+			Collect(c);
+			_state = State.EscapeIntermediate;
+			return;
+		}
+
+		DispatchEscape(c, sink);
+	}
+
+	private void StepEscapeIntermediate(char c, IVtTokenSink sink)
+	{
+		if (c == Escape)
+		{
+			EnterEscape();
+			return;
+		}
+
+		if (c < ' ')
+		{
+			sink.Execute(c);
+			return;
+		}
+
+		if (c <= '/')
+		{
+			Collect(c);
+			return;
+		}
+
+		DispatchEscape(c, sink);
+	}
+
+	private void DispatchEscape(char c, IVtTokenSink sink)
+	{
+		_state = State.Ground;
+		if (c > '~' || _overflow)
+		{
+			sink.Abandoned(VtSequenceKind.Escape);
+			return;
+		}
+
+		sink.Esc(new EscSequence(_intermediates.AsSpan(0, _intermediateCount), c));
+	}
+
+	private void EnterParameters(State state)
+	{
+		_state = state;
+		_parameterCount = 0;
+		_intermediateCount = 0;
+		_prefix = '\0';
+		_parameterStarted = false;
+		_overflow = false;
+	}
+
+	private void EnterString(State state)
+	{
+		_state = state;
+		_string.Clear();
+		_stringEscape = false;
+		_overflow = false;
+	}
+
+	private void StepCsi(char c, IVtTokenSink sink)
+	{
+		if (c == Escape)
+		{
+			sink.Abandoned(VtSequenceKind.Csi);
+			EnterEscape();
+			return;
+		}
+
+		if (c < ' ')
+		{
+			sink.Execute(c);
+			return;
+		}
+
+		if (ReadHeader(c, State.CsiEntry, State.CsiParam, State.CsiIntermediate, State.CsiIgnore)) return;
+
+		_state = State.Ground;
+		if (c is < '@' or > '~' || _overflow)
+		{
+			sink.Abandoned(VtSequenceKind.Csi);
+			return;
+		}
+
+		sink.Csi(Header(c));
+	}
+
+	private void StepDcsHeader(char c, IVtTokenSink sink)
+	{
+		if (c == Escape)
+		{
+			sink.Abandoned(VtSequenceKind.Dcs);
+			EnterEscape();
+			return;
+		}
+
+		// Controls inside a DCS header are ignored, as the state machine has it.
+		if (c < ' ') return;
+
+		if (ReadHeader(c, State.DcsEntry, State.DcsParam, State.DcsIntermediate, State.DcsIgnore)) return;
+
+		if (c is < '@' or > '~')
+		{
+			_overflow = true;
+		}
+
+		_dcsFinal = c;
+		_string.Clear();
+		_stringEscape = false;
+		_state = State.DcsPassthrough;
+	}
+
+	/// <summary>
+	/// Reads one character of a CSI or DCS header: a private prefix, a parameter digit or separator, or an
+	/// intermediate. Returns false when <paramref name="c"/> is the final character.
+	/// </summary>
+	private bool ReadHeader(char c, State entry, State param, State intermediate, State ignore)
+	{
+		if (_state == ignore)
+		{
+			// Ignore everything up to and including the final character.
+			if (c is >= '@' and <= '~')
+			{
+				_overflow = true;
+				return false;
+			}
+
+			return true;
+		}
+
+		if (c is >= '<' and <= '?')
+		{
+			if (_state == entry)
+			{
+				_prefix = c;
+				_state = param;
+			}
+			else
+			{
+				_state = ignore;
+			}
+
+			return true;
+		}
+
+		if (c is >= '0' and <= '9' or ';' or ':')
+		{
+			if (_state == intermediate)
+			{
+				_state = ignore;
+				return true;
+			}
+
+			_state = param;
+			ReadParameter(c);
+			return true;
+		}
+
+		if (c is >= ' ' and <= '/')
+		{
+			Collect(c);
+			_state = intermediate;
+			return true;
+		}
+
+		return false;
+	}
+
+	private void ReadParameter(char c)
+	{
+		if (c is ';' or ':')
+		{
+			if (!_parameterStarted) StartParameter(subparameter: false);
+			// The separator closes this parameter; the next one starts now, empty.
+			if (_parameterCount >= _parameters.Length)
+			{
+				_overflow = true;
+				return;
+			}
+
+			_parameters[_parameterCount] = Omitted;
+			_subparameters[_parameterCount] = c == ':';
+			_parameterCount++;
+			_parameterStarted = true;
+			return;
+		}
+
+		if (!_parameterStarted) StartParameter(subparameter: false);
+		if (_overflow) return;
+
+		var index = _parameterCount - 1;
+		var current = _parameters[index] == Omitted ? 0 : _parameters[index];
+		_parameters[index] = Math.Min(_limits.MaxParameterValue, (current * 10) + (c - '0'));
+	}
+
+	private void StartParameter(bool subparameter)
+	{
+		if (_parameterCount >= _parameters.Length)
+		{
+			_overflow = true;
+			return;
+		}
+
+		_parameters[_parameterCount] = Omitted;
+		_subparameters[_parameterCount] = subparameter;
+		_parameterCount++;
+		_parameterStarted = true;
+	}
+
+	private CsiSequence Header(char final) => new(
+		_prefix,
+		_parameters.AsSpan(0, _parameterCount),
+		_subparameters.AsSpan(0, _parameterCount),
+		_intermediates.AsSpan(0, _intermediateCount),
+		final);
+
+	private void Collect(char c)
+	{
+		if (_intermediateCount < _intermediates.Length) _intermediates[_intermediateCount++] = c;
+		else _overflow = true;
+	}
+
+	private void StepOsc(char c, IVtTokenSink sink)
+	{
+		if (c == Bell)
+		{
+			EndOsc(sink);
+			return;
+		}
+
+		if (_stringEscape)
+		{
+			_stringEscape = false;
+			if (c == '\\')
+			{
+				EndOsc(sink);
+				return;
+			}
+
+			// ESC followed by anything else ends the string and starts a new escape.
+			sink.Abandoned(VtSequenceKind.Osc);
+			EnterEscape();
+			StepEscape(c, sink);
+			return;
+		}
+
+		if (c == Escape)
+		{
+			_stringEscape = true;
+			return;
+		}
+
+		if (c < ' ') return;
+		Append(c, _limits.MaxStringLength);
+	}
+
+	private void EndOsc(IVtTokenSink sink)
+	{
+		_state = State.Ground;
+		if (_overflow)
+		{
+			sink.Abandoned(VtSequenceKind.Osc);
+		}
+		else
+		{
+			sink.Osc(Chunk());
+		}
+
+		_string.Clear();
+	}
+
+	private void StepString(char c, IVtTokenSink sink)
+	{
+		if (_stringEscape)
+		{
+			_stringEscape = false;
+			if (c == '\\')
+			{
+				EndString(sink);
+				return;
+			}
+
+			sink.Abandoned(Kind());
+			EnterEscape();
+			StepEscape(c, sink);
+			return;
+		}
+
+		if (c == Escape)
+		{
+			_stringEscape = true;
+			return;
+		}
+
+		// BEL is not a terminator for these by the standard, but tmux and some programs send it.
+		if (c == Bell)
+		{
+			EndString(sink);
+			return;
+		}
+
+		if (_state == State.IgnoredString) return;
+		if (c < ' ') return;
+
+		Append(c, _state == State.ApcString ? _limits.MaxApcLength : _limits.MaxStringLength);
+	}
+
+	private void EndString(IVtTokenSink sink)
+	{
+		var state = _state;
+		_state = State.Ground;
+		if (state == State.IgnoredString)
+		{
+			_string.Clear();
+			return;
+		}
+
+		if (_overflow)
+		{
+			sink.Abandoned(state == State.ApcString ? VtSequenceKind.Apc : VtSequenceKind.Dcs);
+		}
+		else if (state == State.ApcString)
+		{
+			sink.Apc(Chunk());
+		}
+		else
+		{
+			sink.Dcs(Header(_dcsFinal), Chunk());
+		}
+
+		_string.Clear();
+	}
+
+	private void Append(char c, int max)
+	{
+		if (_overflow) return;
+		if (_string.Length >= max)
+		{
+			_overflow = true;
+			_string.Clear();
+			return;
+		}
+
+		_string.Append(c);
+	}
+
+	private ReadOnlySpan<char> Chunk()
+	{
+		// One chunk is the common case; a multi-chunk builder is copied once.
+		foreach (var chunk in _string.GetChunks())
+		{
+			if (chunk.Length == _string.Length) return chunk.Span;
+			break;
+		}
+
+		return _string.ToString();
+	}
+
+	private VtSequenceKind Kind() => _state switch
+	{
+		State.ApcString => VtSequenceKind.Apc,
+		State.OscString => VtSequenceKind.Osc,
+		State.DcsPassthrough or State.DcsEntry or State.DcsParam or State.DcsIntermediate or State.DcsIgnore => VtSequenceKind.Dcs,
+		State.CsiEntry or State.CsiParam or State.CsiIntermediate or State.CsiIgnore => VtSequenceKind.Csi,
+		_ => VtSequenceKind.Escape,
+	};
+
+	private void Abandon(IVtTokenSink sink)
+	{
+		if (_state is State.Ground) return;
+		var kind = Kind();
+		var ignored = _state == State.IgnoredString;
+		_state = State.Ground;
+		_string.Clear();
+		if (!ignored) sink.Abandoned(kind);
+	}
+}
+
+/// <summary>The kinds of sequence a <see cref="VtTokenizer"/> recognises.</summary>
+public enum VtSequenceKind
+{
+	/// <summary>A two-character escape, <c>ESC</c> then a final character, with intermediates.</summary>
+	Escape,
+
+	/// <summary>A control sequence, <c>ESC [</c>.</summary>
+	Csi,
+
+	/// <summary>An operating system command, <c>ESC ]</c>.</summary>
+	Osc,
+
+	/// <summary>A device control string, <c>ESC P</c>.</summary>
+	Dcs,
+
+	/// <summary>An application program command, <c>ESC _</c>.</summary>
+	Apc,
+}
+
+/// <summary>How far a <see cref="VtTokenizer"/> lets a sequence grow.</summary>
+public sealed record VtLimits
+{
+	/// <summary>The defaults: 32 parameters, as <c>vte</c> has, a 16 MiB string for a sixel or iTerm2 picture, and 64 KiB for an APC.</summary>
+	public static VtLimits Default { get; } = new();
+
+	/// <summary>The most parameters a CSI or DCS header may have, subparameters included.</summary>
+	public int MaxParameters { get; init; } = 32;
+
+	/// <summary>The largest value a parameter is read as; larger values are clamped to it.</summary>
+	public int MaxParameterValue { get; init; } = 65535;
+
+	/// <summary>The longest OSC or DCS payload, in characters.</summary>
+	public int MaxStringLength { get; init; } = 16 * 1024 * 1024;
+
+	/// <summary>The longest APC payload, in characters. Kitty sends pictures in chunks of 4096.</summary>
+	public int MaxApcLength { get; init; } = 64 * 1024;
+}
diff --git a/MarkupString/Display/CellRenderer.cs b/MarkupString/Display/CellRenderer.cs
new file mode 100644
index 0000000..d6a849d
--- /dev/null
+++ b/MarkupString/Display/CellRenderer.cs
@@ -0,0 +1,236 @@
+namespace MarkupString.Display;
+
+/// <summary>
+/// One cell of a <see cref="CellLayout"/>: a grapheme and how it looks. A wide grapheme takes two cells, the
+/// second a continuation with empty <see cref="Text"/>.
+/// </summary>
+/// <param name="Text">The grapheme, or empty for the right half of a wide one.</param>
+/// <param name="Style">How it looks.</param>
+public readonly record struct Cell(string Text, DisplayStyle Style)
+{
+	/// <summary>Cells the grapheme takes: 1 or 2, or 0 for a continuation.</summary>
+	public int Width { get; init; } = 1;
+
+	/// <summary>
+	/// For a cell of a picture (<see cref="DisplayStyle.Picture"/> set), its column in the picture, counted in
+	/// cells from the picture's left edge; with the picture's <see cref="PictureRow.Row"/> it says which part of
+	/// the picture to draw here.
+	/// </summary>
+	public int PictureColumn { get; init; }
+
+	/// <summary>Whether this is the right half of a wide grapheme.</summary>
+	public bool IsContinuation => Width == 0;
+}
+
+/// <summary>A point (a bell, a sound) and the cell it stands before.</summary>
+/// <param name="Row">The row.</param>
+/// <param name="Column">The column.</param>
+/// <param name="Markup">The point.</param>
+public readonly record struct CellPoint(int Row, int Column, IPointMarkup Markup);
+
+/// <summary>One row of a <see cref="CellLayout"/>.</summary>
+public sealed class CellRow
+{
+	internal CellRow(List<Cell> cells, bool wrapped)
+	{
+		Cells = cells;
+		Wrapped = wrapped;
+	}
+
+	/// <summary>The cells, left to right. A row is as long as its text, never padded to the width.</summary>
+	public IReadOnlyList<Cell> Cells { get; }
+
+	/// <summary>Whether the next row continues this one because the text was wrapped, not because a line ended.</summary>
+	public bool Wrapped { get; }
+}
+
+/// <summary>Text laid out on a grid of cells: what a cell renderer draws and hit tests against.</summary>
+public sealed class CellLayout
+{
+	internal CellLayout(List<CellRow> rows, List<CellPoint> points, int columns)
+	{
+		Rows = rows;
+		Points = points;
+		Columns = columns;
+	}
+
+	/// <summary>The rows, top to bottom.</summary>
+	public IReadOnlyList<CellRow> Rows { get; }
+
+	/// <summary>The points, in order.</summary>
+	public IReadOnlyList<CellPoint> Points { get; }
+
+	/// <summary>The width it was laid out to, or 0 for unwrapped.</summary>
+	public int Columns { get; }
+
+	/// <summary>The cell at <paramref name="row"/> and <paramref name="column"/>, or null past the text.</summary>
+	public Cell? At(int row, int column)
+	{
+		if (row < 0 || row >= Rows.Count || column < 0) return null;
+		var cells = Rows[row].Cells;
+		return column < cells.Count ? cells[column] : null;
+	}
+
+	/// <summary>
+	/// What clicking the cell at <paramref name="row"/> and <paramref name="column"/> does, or null. The right half
+	/// of a wide grapheme answers for the whole of it.
+	/// </summary>
+	public Interaction? InteractionAt(int row, int column)
+	{
+		if (At(row, column) is not { } cell) return null;
+		if (cell.IsContinuation && column > 0) cell = Rows[row].Cells[column - 1];
+		return cell.Style.Interaction;
+	}
+}
+
+/// <summary>
+/// Lays text out on a grid of cells, for an output that draws cells itself: a Skia window, a terminal emulator's
+/// buffer. Graphemes are measured with <see cref="DisplayWidth"/>; tabs advance to the next stop.
+/// </summary>
+public static class CellRenderer
+{
+	/// <summary>Lays <paramref name="text"/> out.</summary>
+	/// <param name="text">The text; a line feed in it starts a new row.</param>
+	/// <param name="columns">The width to wrap at, or 0 not to wrap.</param>
+	/// <param name="registry">The styles.</param>
+	/// <param name="options">The output.</param>
+	/// <param name="wordWrap">Wrap at the last space that fits, rather than at the last cell.</param>
+	public static CellLayout Layout(MarkupText text, int columns, DisplayRegistry registry, DisplayOptions options, bool wordWrap = false)
+	{
+		ArgumentNullException.ThrowIfNull(text);
+		ArgumentNullException.ThrowIfNull(registry);
+		ArgumentNullException.ThrowIfNull(options);
+		ArgumentOutOfRangeException.ThrowIfNegative(columns);
+
+		var builder = new Builder(columns, Math.Max(1, options.TabWidth), wordWrap);
+		var styles = new Dictionary<MarkupSet, DisplayStyle>(ReferenceEqualityComparer.Instance);
+		var fold = options.Capabilities.Unicode == UnicodeLevel.Ascii;
+		var narrow = options.Capabilities.Unicode != UnicodeLevel.Full;
+		var source = text.Text;
+		var at = 0;
+
+		foreach (var run in text.Runs)
+		{
+			if (run.Start > at) builder.Write(Fold(source[at..run.Start], fold), DisplayStyle.Plain, narrow);
+
+			var point = SpanRenderer.FindPoint(run.Markups);
+			if (point is not null)
+			{
+				if (SpanRenderer.Shows(point, options.Capabilities)) builder.Point(point);
+			}
+			else
+			{
+				if (!styles.TryGetValue(run.Markups, out var style))
+				{
+					styles[run.Markups] = style = registry.Resolve(run.Markups, options);
+				}
+
+				builder.Write(Fold(source.Substring(run.Start, run.Length), fold), style, narrow);
+			}
+
+			at = run.End;
+		}
+
+		if (at < source.Length) builder.Write(Fold(source[at..], fold), DisplayStyle.Plain, narrow);
+		return builder.Finish();
+	}
+
+	private static string Fold(string text, bool fold) => fold ? AsciiFold.Default.Fold(text) : text;
+
+	private sealed class Builder(int columns, int tabWidth, bool wordWrap)
+	{
+		private readonly List<CellRow> _rows = [];
+		private readonly List<CellPoint> _points = [];
+		private List<Cell> _row = [];
+
+		public void Point(IPointMarkup point) => _points.Add(new CellPoint(_rows.Count, _row.Count, point));
+
+		public void Write(string text, DisplayStyle style, bool narrow)
+		{
+			foreach (var range in Graphemes.Enumerate(text))
+			{
+				var grapheme = text[range];
+				switch (grapheme)
+				{
+					case "\n":
+					case "\r\n":
+						EndRow(wrapped: false);
+						continue;
+					case "\t":
+						var stop = (_row.Count / tabWidth + 1) * tabWidth;
+						if (columns > 0) stop = Math.Min(stop, columns);
+						if (stop <= _row.Count) stop = _row.Count + 1;
+						while (_row.Count < stop) Put(new Cell(" ", style));
+						continue;
+				}
+
+				var width = DisplayWidth.Of(grapheme);
+				if (width <= 0)
+				{
+					// A control character, or a mark with nothing before it on the row: it takes no cell.
+					if (_row.Count > 0 && !char.IsControl(grapheme[0]) && _row[^1] is { IsContinuation: false } last)
+					{
+						_row[^1] = last with { Text = last.Text + grapheme };
+					}
+
+					continue;
+				}
+
+				if (width > 2) width = 2;
+				if (narrow && width == 2)
+				{
+					grapheme = "?";
+					width = 1;
+				}
+
+				var pictureColumn = 0;
+				if (style.Picture is { } picture)
+				{
+					pictureColumn = _row.Count > 0 && _row[^1].Style.Picture is { } previous && ReferenceEquals(previous, picture)
+						? _row[^1].PictureColumn + 1
+						: picture.Row?.FirstColumn ?? 0;
+				}
+
+				if (columns > 0 && _row.Count + width > columns) Wrap(width);
+				Put(new Cell(grapheme, style) { Width = width, PictureColumn = pictureColumn });
+				if (width == 2) _row.Add(new Cell(string.Empty, style) { Width = 0, PictureColumn = pictureColumn + 1 });
+			}
+		}
+
+		public CellLayout Finish()
+		{
+			if (_row.Count > 0 || _rows.Count == 0 || _points.Exists(point => point.Row == _rows.Count)) EndRow(wrapped: false);
+			return new CellLayout(_rows, _points, columns);
+		}
+
+		private void Put(Cell cell)
+		{
+			if (columns > 0 && _row.Count >= columns) Wrap(cell.Width);
+			_row.Add(cell);
+		}
+
+		private void Wrap(int width)
+		{
+			if (wordWrap)
+			{
+				var space = _row.FindLastIndex(cell => cell.Text == " " && cell.Style.Picture is null);
+				if (space > 0)
+				{
+					var carried = _row.GetRange(space + 1, _row.Count - space - 1);
+					_row.RemoveRange(space + 1, _row.Count - space - 1);
+					EndRow(wrapped: true);
+					_row.AddRange(carried);
+					return;
+				}
+			}
+
+			EndRow(wrapped: true);
+		}
+
+		private void EndRow(bool wrapped)
+		{
+			_rows.Add(new CellRow(_row, wrapped));
+			_row = [];
+		}
+	}
+}
diff --git a/MarkupString/Display/DisplayRegistry.cs b/MarkupString/Display/DisplayRegistry.cs
new file mode 100644
index 0000000..ed7b51b
--- /dev/null
+++ b/MarkupString/Display/DisplayRegistry.cs
@@ -0,0 +1,147 @@
+namespace MarkupString.Display;
+
+/// <summary>
+/// The style contributors a structured renderer folds markup with. Immutable; build one once with
+/// <c>With(...)</c> and share it.
+/// </summary>
+public sealed class DisplayRegistry
+{
+	private readonly IStyleContributor[] _contributors;
+
+	private DisplayRegistry(IStyleContributor[] contributors) => _contributors = contributors;
+
+	/// <summary>A registry that knows no markup: everything is plain.</summary>
+	public static DisplayRegistry Empty { get; } = new([]);
+
+	/// <summary>A registry that knows the shared vocabulary: pictures, panes, menus and highlights.</summary>
+	public static DisplayRegistry Core { get; } = Empty.With(VocabularyStyles.Instance);
+
+	/// <summary>The contributors, in the order they run.</summary>
+	public IReadOnlyList<IStyleContributor> Contributors => _contributors;
+
+	/// <summary>A registry with <paramref name="contributor"/> added after the others.</summary>
+	public DisplayRegistry With(IStyleContributor contributor)
+	{
+		ArgumentNullException.ThrowIfNull(contributor);
+		return new DisplayRegistry([.. _contributors, contributor]);
+	}
+
+	/// <summary>Folds <paramref name="markups"/> into one style, degraded to what <paramref name="options"/> can show.</summary>
+	public DisplayStyle Resolve(MarkupSet? markups, DisplayOptions options)
+	{
+		ArgumentNullException.ThrowIfNull(options);
+		if (markups is null || markups.Count == 0) return DisplayStyle.Plain;
+
+		var builder = new StyleBuilder();
+		foreach (var contributor in _contributors) contributor.Contribute(markups, builder, options);
+		return Degrade(builder, options);
+	}
+
+	private static DisplayStyle Degrade(StyleBuilder style, DisplayOptions options)
+	{
+		var capabilities = options.Capabilities;
+
+		if (capabilities.Colors <= ColorLevel.Attributes)
+		{
+			style.Foreground = null;
+			style.Background = null;
+		}
+
+		style.Attributes &= capabilities.Colors == ColorLevel.None ? TextAttributes.None : capabilities.Attributes | TextAttributes.Inverse;
+
+		if (style.Has(TextAttributes.Inverse))
+		{
+			if (capabilities.Colors <= ColorLevel.Attributes && (capabilities.Attributes & TextAttributes.Inverse) == 0)
+			{
+				style.Attributes &= ~TextAttributes.Inverse;
+			}
+			else if (capabilities.Colors > ColorLevel.Attributes)
+			{
+				(style.Foreground, style.Background) = (style.Background ?? options.DefaultBackground, style.Foreground ?? options.DefaultForeground);
+			}
+		}
+
+		if (style.Foreground is { } foreground && options.Colors is { } resolver)
+		{
+			style.Foreground = resolver.Legible(foreground, style.Background ?? options.DefaultBackground);
+		}
+
+		if (style.Interaction is { } interaction) style.Interaction = Degrade(interaction, capabilities.Interactions);
+		if (capabilities.Pictures == PictureMethods.None) style.Picture = null;
+		if (!capabilities.Panes) style.Pane = null;
+
+		return style.Build();
+	}
+
+	private static Interaction? Degrade(Interaction interaction, InteractionKinds allowed)
+	{
+		if (interaction.Choices is { Count: > 0 } && (allowed & InteractionKinds.Menu) == 0)
+		{
+			interaction = interaction with { Choices = null };
+		}
+
+		var kind = interaction.Kind switch
+		{
+			InteractionKind.Url => InteractionKinds.Url,
+			InteractionKind.Command => InteractionKinds.Command,
+			_ => InteractionKinds.Prompt,
+		};
+
+		if ((allowed & kind) != 0) return interaction;
+
+		// A prompt link on an output that only sends commands is still useful as a command.
+		if (interaction.Kind == InteractionKind.Prompt && (allowed & InteractionKinds.Command) != 0)
+		{
+			return interaction with { Kind = InteractionKind.Command };
+		}
+
+		return null;
+	}
+}
+
+file static class StyleBuilderExtensions
+{
+	public static bool Has(this StyleBuilder style, TextAttributes attribute) => (style.Attributes & attribute) == attribute;
+}
+
+/// <summary>Styles for the shared vocabulary: pictures, panes, command menus and highlights.</summary>
+public sealed class VocabularyStyles : IStyleContributor
+{
+	/// <summary>The one instance.</summary>
+	public static VocabularyStyles Instance { get; } = new();
+
+	private VocabularyStyles()
+	{
+	}
+
+	/// <inheritdoc/>
+	public void Contribute(MarkupSet markups, StyleBuilder style, DisplayOptions options)
+	{
+		ArgumentNullException.ThrowIfNull(markups);
+		ArgumentNullException.ThrowIfNull(style);
+
+		// Outermost first, so the innermost layer has the last word.
+		for (var i = markups.Count - 1; i >= 0; i--)
+		{
+			switch (markups[i])
+			{
+				case ImageMarkup image:
+					style.Picture = image;
+					break;
+				case PaneMarkup pane:
+					style.Pane = pane.Name;
+					break;
+				case CommandMenuMarkup menu when menu.Choices.Count > 0:
+					style.Interaction = new Interaction(InteractionKind.Command, menu.Choices[0].Command)
+					{
+						Hint = menu.Hint,
+						Choices = menu.Choices,
+					};
+					break;
+				case HighlightMarkup highlight:
+					style.Background = highlight.Color;
+					break;
+			}
+		}
+	}
+}
diff --git a/MarkupString/Display/DisplayStyle.cs b/MarkupString/Display/DisplayStyle.cs
new file mode 100644
index 0000000..0f14687
--- /dev/null
+++ b/MarkupString/Display/DisplayStyle.cs
@@ -0,0 +1,162 @@
+namespace MarkupString.Display;
+
+/// <summary>What clicking a stretch of text does.</summary>
+public enum InteractionKind
+{
+	/// <summary>Opens <see cref="Interaction.Target"/>, an address.</summary>
+	Url,
+
+	/// <summary>Sends <see cref="Interaction.Target"/> to the game as a command.</summary>
+	Command,
+
+	/// <summary>Puts <see cref="Interaction.Target"/> in the input line, for the player to finish and send.</summary>
+	Prompt,
+}
+
+/// <summary>A clickable stretch of text, resolved from whichever markup made it clickable.</summary>
+/// <param name="Kind">What a click does.</param>
+/// <param name="Target">The address or command.</param>
+public sealed record Interaction(InteractionKind Kind, string Target)
+{
+	/// <summary>A hint to show on hover, or null.</summary>
+	public string? Hint { get; init; }
+
+	/// <summary>A menu of further choices (MXP <c>&lt;SEND href="a|b"&gt;</c>), or null. <see cref="Target"/> is the first.</summary>
+	public IReadOnlyList<CommandChoice>? Choices { get; init; }
+
+	/// <summary>
+	/// Text with the same group is one link for hover and focus, even across lines (an OSC 8 <c>id</c>). Null groups
+	/// by <see cref="Target"/> alone.
+	/// </summary>
+	public string? Group { get; init; }
+
+	/// <summary>Value equality, the choices compared item by item.</summary>
+	public bool Equals(Interaction? other) =>
+		other is not null
+		&& Kind == other.Kind
+		&& string.Equals(Target, other.Target, StringComparison.Ordinal)
+		&& string.Equals(Hint, other.Hint, StringComparison.Ordinal)
+		&& string.Equals(Group, other.Group, StringComparison.Ordinal)
+		&& (ReferenceEquals(Choices, other.Choices) || (Choices is not null && other.Choices is not null && Choices.SequenceEqual(other.Choices)));
+
+	/// <inheritdoc/>
+	public override int GetHashCode() => HashCode.Combine(Kind, Target, Hint, Group, Choices?.Count ?? -1);
+}
+
+/// <summary>
+/// How a stretch of text looks once every layer of its markup is folded together and resolved to colours: what a
+/// cell or a span is drawn with. Colours are RGB, already swapped when the text is inverse.
+/// </summary>
+public readonly record struct DisplayStyle
+{
+	/// <summary>The text colour, or null for the output's default.</summary>
+	public RgbColor? Foreground { get; init; }
+
+	/// <summary>The background colour, or null for the output's default.</summary>
+	public RgbColor? Background { get; init; }
+
+	/// <summary>The attributes. <see cref="TextAttributes.Inverse"/> stays set for information; the colours are already swapped.</summary>
+	public TextAttributes Attributes { get; init; }
+
+	/// <summary>What clicking it does, or null.</summary>
+	public Interaction? Interaction { get; init; }
+
+	/// <summary>The picture these cells are part of, or null.</summary>
+	public ImageMarkup? Picture { get; init; }
+
+	/// <summary>The pane it belongs in, or null for the main output.</summary>
+	public string? Pane { get; init; }
+
+	/// <summary>No styling at all.</summary>
+	public static DisplayStyle Plain => default;
+
+	/// <summary>Whether <paramref name="attribute"/> is set.</summary>
+	public bool Has(TextAttributes attribute) => (Attributes & attribute) == attribute;
+}
+
+/// <summary>
+/// Collects a style as contributors fold a run's markup into it. Contributors run in the order they were added to
+/// the <see cref="DisplayRegistry"/>; each reads the layers it knows and leaves the rest.
+/// </summary>
+public sealed class StyleBuilder
+{
+	/// <summary>The text colour so far, or null.</summary>
+	public RgbColor? Foreground { get; set; }
+
+	/// <summary>The background colour so far, or null.</summary>
+	public RgbColor? Background { get; set; }
+
+	/// <summary>The attributes so far.</summary>
+	public TextAttributes Attributes { get; set; }
+
+	/// <summary>The interaction so far, or null.</summary>
+	public Interaction? Interaction { get; set; }
+
+	/// <summary>The picture so far, or null.</summary>
+	public ImageMarkup? Picture { get; set; }
+
+	/// <summary>The pane so far, or null.</summary>
+	public string? Pane { get; set; }
+
+	internal void Clear()
+	{
+		Foreground = null;
+		Background = null;
+		Attributes = TextAttributes.None;
+		Interaction = null;
+		Picture = null;
+		Pane = null;
+	}
+
+	internal DisplayStyle Build() => new()
+	{
+		Foreground = Foreground,
+		Background = Background,
+		Attributes = Attributes,
+		Interaction = Interaction,
+		Picture = Picture,
+		Pane = Pane,
+	};
+}
+
+/// <summary>Folds the layers it knows of a run's markup into a <see cref="StyleBuilder"/>.</summary>
+public interface IStyleContributor
+{
+	/// <summary>Reads <paramref name="markups"/> (innermost first) and adds what it knows to <paramref name="style"/>.</summary>
+	void Contribute(MarkupSet markups, StyleBuilder style, DisplayOptions options);
+}
+
+/// <summary>Turns a palette colour into RGB, so a client's theme decides what "red" is.</summary>
+public interface IColorResolver
+{
+	/// <summary>One of the sixteen standard colours: <paramref name="index"/> 0 to 7, bright or not.</summary>
+	RgbColor Standard(int index, bool bright);
+
+	/// <summary>An entry of the 256-colour palette.</summary>
+	RgbColor Xterm(int index);
+
+	/// <summary>
+	/// The colour text is finally drawn in, given its background: where a client keeps text legible against its
+	/// background, it changes the colour here. Return <paramref name="foreground"/> to leave it alone.
+	/// </summary>
+	RgbColor Legible(RgbColor foreground, RgbColor background);
+}
+
+/// <summary>What a structured renderer is drawing for.</summary>
+public sealed record DisplayOptions
+{
+	/// <summary>What the output can show; whatever it cannot is dropped from each style.</summary>
+	public OutputCapabilities Capabilities { get; init; } = OutputCapabilities.Browser;
+
+	/// <summary>How palette colours become RGB, or null for the xterm palette.</summary>
+	public IColorResolver? Colors { get; init; }
+
+	/// <summary>The default text colour, used when inverse text has no colour of its own.</summary>
+	public RgbColor DefaultForeground { get; init; } = new(229, 229, 229);
+
+	/// <summary>The default background, used when inverse text has no background of its own.</summary>
+	public RgbColor DefaultBackground { get; init; } = new(0, 0, 0);
+
+	/// <summary>How many cells a tab advances to, in the cell renderer.</summary>
+	public int TabWidth { get; init; } = 8;
+}
diff --git a/MarkupString/Display/OutputCapabilities.cs b/MarkupString/Display/OutputCapabilities.cs
new file mode 100644
index 0000000..1b2559d
--- /dev/null
+++ b/MarkupString/Display/OutputCapabilities.cs
@@ -0,0 +1,223 @@
+namespace MarkupString.Display;
+
+/// <summary>How many colours an output can show.</summary>
+public enum ColorLevel
+{
+	/// <summary>No colour, and no attributes either.</summary>
+	None,
+
+	/// <summary>No colour, but attributes such as bold and underline.</summary>
+	Attributes,
+
+	/// <summary>The sixteen standard colours.</summary>
+	Standard,
+
+	/// <summary>The xterm 256-colour palette.</summary>
+	Xterm256,
+
+	/// <summary>Any RGB colour.</summary>
+	TrueColor,
+}
+
+/// <summary>Text attributes, as an output can draw them and a <see cref="DisplayStyle"/> carries them.</summary>
+[Flags]
+public enum TextAttributes
+{
+	/// <summary>None.</summary>
+	None = 0,
+
+	/// <summary>Bold, or bright.</summary>
+	Bold = 1 << 0,
+
+	/// <summary>Faint, or dim.</summary>
+	Faint = 1 << 1,
+
+	/// <summary>Italic.</summary>
+	Italic = 1 << 2,
+
+	/// <summary>Underlined.</summary>
+	Underline = 1 << 3,
+
+	/// <summary>Blinking.</summary>
+	Blink = 1 << 4,
+
+	/// <summary>Foreground and background swapped.</summary>
+	Inverse = 1 << 5,
+
+	/// <summary>Hidden: drawn in the background colour, but still text.</summary>
+	Conceal = 1 << 6,
+
+	/// <summary>Struck through.</summary>
+	Strikethrough = 1 << 7,
+
+	/// <summary>A line over the text.</summary>
+	Overline = 1 << 8,
+
+	/// <summary>Every attribute.</summary>
+	All = Bold | Faint | Italic | Underline | Blink | Inverse | Conceal | Strikethrough | Overline,
+}
+
+/// <summary>What an output does when the text it shows is clicked.</summary>
+[Flags]
+public enum InteractionKinds
+{
+	/// <summary>Nothing is clickable.</summary>
+	None = 0,
+
+	/// <summary>A link opens an address.</summary>
+	Url = 1,
+
+	/// <summary>A link sends a command to the game.</summary>
+	Command = 2,
+
+	/// <summary>A link puts a command in the input line without sending it.</summary>
+	Prompt = 4,
+
+	/// <summary>A link offers a menu of commands.</summary>
+	Menu = 8,
+
+	/// <summary>Every kind.</summary>
+	All = Url | Command | Prompt | Menu,
+}
+
+/// <summary>The ways an output can draw a picture, best first.</summary>
+[Flags]
+public enum PictureMethods
+{
+	/// <summary>Pictures are shown as their text.</summary>
+	None = 0,
+
+	/// <summary>The output draws pixels itself: a window, or a browser.</summary>
+	Bitmap = 1,
+
+	/// <summary>Kitty graphics drawn with Unicode placeholders.</summary>
+	KittyPlaceholders = 2,
+
+	/// <summary>iTerm2 inline images.</summary>
+	InlineImages = 4,
+
+	/// <summary>Sixel graphics.</summary>
+	Sixel = 8,
+
+	/// <summary>Coloured half blocks, two pixels to a cell.</summary>
+	HalfBlocks = 16,
+}
+
+/// <summary>How much of Unicode an output can draw.</summary>
+public enum UnicodeLevel
+{
+	/// <summary>Everything, wide characters and emoji included.</summary>
+	Full,
+
+	/// <summary>Everything that is one cell wide.</summary>
+	Narrow,
+
+	/// <summary>ASCII only; the rest is folded with <see cref="AsciiFold"/>.</summary>
+	Ascii,
+}
+
+/// <summary>
+/// What one output can show. A renderer reads it to decide how far to degrade what it was given, and a client
+/// reads it to decide what to tell the server it accepts.
+/// </summary>
+public sealed record OutputCapabilities
+{
+	/// <summary>How many colours it shows.</summary>
+	public ColorLevel Colors { get; init; } = ColorLevel.TrueColor;
+
+	/// <summary>The attributes it draws. Blink is often left out by choice.</summary>
+	public TextAttributes Attributes { get; init; } = TextAttributes.All;
+
+	/// <summary>What happens when text is clicked.</summary>
+	public InteractionKinds Interactions { get; init; } = InteractionKinds.All;
+
+	/// <summary>How it draws pictures.</summary>
+	public PictureMethods Pictures { get; init; }
+
+	/// <summary>Whether a moving picture plays rather than showing its first frame.</summary>
+	public bool MovingPictures { get; init; }
+
+	/// <summary>Whether it plays sounds.</summary>
+	public bool Sound { get; init; }
+
+	/// <summary>Whether it shows text in named panes apart from the main output.</summary>
+	public bool Panes { get; init; }
+
+	/// <summary>How much of Unicode it draws.</summary>
+	public UnicodeLevel Unicode { get; init; } = UnicodeLevel.Full;
+
+	/// <summary>Plain text and nothing else.</summary>
+	public static OutputCapabilities PlainText { get; } = new()
+	{
+		Colors = ColorLevel.None,
+		Attributes = TextAttributes.None,
+		Interactions = InteractionKinds.None,
+	};
+
+	/// <summary>A grid of cells the client draws itself, such as a window drawn with Skia.</summary>
+	public static OutputCapabilities CellGrid { get; } = new()
+	{
+		Pictures = PictureMethods.Bitmap | PictureMethods.HalfBlocks,
+		MovingPictures = true,
+		Sound = true,
+		Panes = true,
+	};
+
+	/// <summary>A web page.</summary>
+	public static OutputCapabilities Browser { get; } = new()
+	{
+		Pictures = PictureMethods.Bitmap,
+		MovingPictures = true,
+		Sound = true,
+		Panes = true,
+	};
+
+	/// <summary>
+	/// What both this output and <paramref name="other"/> can show: the lesser colour level and Unicode level,
+	/// and the shared attributes, interactions and picture methods.
+	/// </summary>
+	public OutputCapabilities Intersect(OutputCapabilities other)
+	{
+		ArgumentNullException.ThrowIfNull(other);
+		return new OutputCapabilities
+		{
+			Colors = (ColorLevel)Math.Min((int)Colors, (int)other.Colors),
+			Attributes = Attributes & other.Attributes,
+			Interactions = Interactions & other.Interactions,
+			Pictures = Pictures & other.Pictures,
+			MovingPictures = MovingPictures && other.MovingPictures,
+			Sound = Sound && other.Sound,
+			Panes = Panes && other.Panes,
+			Unicode = (UnicodeLevel)Math.Max((int)Unicode, (int)other.Unicode),
+		};
+	}
+
+	/// <summary>
+	/// What both this output and <paramref name="other"/> together can show, for a client that shows one session in
+	/// two places and tells the server once.
+	/// </summary>
+	public OutputCapabilities Union(OutputCapabilities other)
+	{
+		ArgumentNullException.ThrowIfNull(other);
+		return new OutputCapabilities
+		{
+			Colors = (ColorLevel)Math.Max((int)Colors, (int)other.Colors),
+			Attributes = Attributes | other.Attributes,
+			Interactions = Interactions | other.Interactions,
+			Pictures = Pictures | other.Pictures,
+			MovingPictures = MovingPictures || other.MovingPictures,
+			Sound = Sound || other.Sound,
+			Panes = Panes || other.Panes,
+			Unicode = (UnicodeLevel)Math.Min((int)Unicode, (int)other.Unicode),
+		};
+	}
+
+	/// <summary>The best way it draws a picture, or <see cref="PictureMethods.None"/>.</summary>
+	public PictureMethods BestPictureMethod =>
+		(Pictures & PictureMethods.Bitmap) != 0 ? PictureMethods.Bitmap
+		: (Pictures & PictureMethods.KittyPlaceholders) != 0 ? PictureMethods.KittyPlaceholders
+		: (Pictures & PictureMethods.InlineImages) != 0 ? PictureMethods.InlineImages
+		: (Pictures & PictureMethods.Sixel) != 0 ? PictureMethods.Sixel
+		: (Pictures & PictureMethods.HalfBlocks) != 0 ? PictureMethods.HalfBlocks
+		: PictureMethods.None;
+}
diff --git a/MarkupString/Display/SpanRenderer.cs b/MarkupString/Display/SpanRenderer.cs
new file mode 100644
index 0000000..f34a79e
--- /dev/null
+++ b/MarkupString/Display/SpanRenderer.cs
@@ -0,0 +1,146 @@
+using System.Globalization;
+using System.Text;
+namespace MarkupString.Display;
+
+/// <summary>
+/// A stretch of text with one style, or a point (a bell, a sound) when <see cref="Point"/> is set and
+/// <see cref="Text"/> is empty.
+/// </summary>
+/// <param name="Text">The text.</param>
+/// <param name="Style">How it looks.</param>
+public readonly record struct DisplaySpan(string Text, DisplayStyle Style)
+{
+	/// <summary>The point that stands here, or null for text.</summary>
+	public IPointMarkup? Point { get; init; }
+}
+
+/// <summary>
+/// Turns text into spans, each one style, for an output that draws runs of text: a web page, a rich text
+/// control. Adjacent text with the same style is one span; a picture row is one span of its blank cells.
+/// </summary>
+public static class SpanRenderer
+{
+	/// <summary>The spans of <paramref name="text"/>, in order.</summary>
+	public static IReadOnlyList<DisplaySpan> Render(MarkupText text, DisplayRegistry registry, DisplayOptions options)
+	{
+		ArgumentNullException.ThrowIfNull(text);
+		ArgumentNullException.ThrowIfNull(registry);
+		ArgumentNullException.ThrowIfNull(options);
+
+		var spans = new List<DisplaySpan>();
+		var styles = new Dictionary<MarkupSet, DisplayStyle>(ReferenceEqualityComparer.Instance);
+		var fold = options.Capabilities.Unicode == UnicodeLevel.Ascii;
+		var source = text.Text;
+		var at = 0;
+
+		foreach (var run in text.Runs)
+		{
+			if (run.Start > at) Add(spans, source[at..run.Start], DisplayStyle.Plain, fold);
+
+			var point = FindPoint(run.Markups);
+			if (point is not null)
+			{
+				if (Shows(point, options.Capabilities)) spans.Add(new DisplaySpan(string.Empty, DisplayStyle.Plain) { Point = point });
+			}
+			else
+			{
+				if (!styles.TryGetValue(run.Markups, out var style))
+				{
+					styles[run.Markups] = style = registry.Resolve(run.Markups, options);
+				}
+
+				Add(spans, source.Substring(run.Start, run.Length), style, fold);
+			}
+
+			at = run.End;
+		}
+
+		if (at < source.Length) Add(spans, source[at..], DisplayStyle.Plain, fold);
+		return spans;
+	}
+
+	/// <summary>
+	/// The inline CSS for <paramref name="style"/>: colours, weight, slant and decorations. Empty for plain text.
+	/// Blink is left to <see cref="CssClasses"/>, since CSS has no blink of its own.
+	/// </summary>
+	public static string Css(DisplayStyle style)
+	{
+		var css = new StringBuilder();
+		if (style.Foreground is { } foreground) Append(css, "color", Hex(foreground));
+		if (style.Background is { } background) Append(css, "background-color", Hex(background));
+		if (style.Has(TextAttributes.Bold)) Append(css, "font-weight", "bold");
+		if (style.Has(TextAttributes.Faint)) Append(css, "opacity", "0.6");
+		if (style.Has(TextAttributes.Italic)) Append(css, "font-style", "italic");
+
+		var lines = new List<string>(3);
+		if (style.Has(TextAttributes.Underline)) lines.Add("underline");
+		if (style.Has(TextAttributes.Overline)) lines.Add("overline");
+		if (style.Has(TextAttributes.Strikethrough)) lines.Add("line-through");
+		if (lines.Count > 0) Append(css, "text-decoration", string.Join(' ', lines));
+
+		if (style.Has(TextAttributes.Conceal)) Append(css, "color", "transparent");
+		return css.ToString();
+	}
+
+	/// <summary>
+	/// The class names a page styles itself: <c>ms-blink</c>, <c>ms-conceal</c>, <c>ms-link</c>, <c>ms-command</c>,
+	/// <c>ms-prompt</c>, <c>ms-menu</c> and <c>ms-picture</c>. Empty for plain text.
+	/// </summary>
+	public static string CssClasses(DisplayStyle style)
+	{
+		var classes = new List<string>(3);
+		if (style.Has(TextAttributes.Blink)) classes.Add("ms-blink");
+		if (style.Has(TextAttributes.Conceal)) classes.Add("ms-conceal");
+		if (style.Interaction is { } interaction)
+		{
+			classes.Add(interaction.Kind switch
+			{
+				InteractionKind.Url => "ms-link",
+				InteractionKind.Command => "ms-command",
+				_ => "ms-prompt",
+			});
+			if (interaction.Choices is { Count: > 1 }) classes.Add("ms-menu");
+		}
+
+		if (style.Picture is not null) classes.Add("ms-picture");
+		return string.Join(' ', classes);
+	}
+
+	/// <summary><paramref name="color"/> as <c>#rrggbb</c>.</summary>
+	public static string Hex(RgbColor color) => string.Create(CultureInfo.InvariantCulture, $"#{color.R:x2}{color.G:x2}{color.B:x2}");
+
+	internal static IPointMarkup? FindPoint(MarkupSet markups)
+	{
+		foreach (var markup in markups)
+		{
+			if (markup is IPointMarkup point) return point;
+		}
+
+		return null;
+	}
+
+	internal static bool Shows(IPointMarkup point, OutputCapabilities capabilities) => point switch
+	{
+		SoundMarkup or SoundStopMarkup => capabilities.Sound,
+		_ => true,
+	};
+
+	private static void Add(List<DisplaySpan> spans, string text, DisplayStyle style, bool fold)
+	{
+		if (text.Length == 0) return;
+		if (fold) text = AsciiFold.Default.Fold(text);
+		if (spans.Count > 0 && spans[^1] is { Point: null } last && last.Style == style)
+		{
+			spans[^1] = last with { Text = last.Text + text };
+			return;
+		}
+
+		spans.Add(new DisplaySpan(text, style));
+	}
+
+	private static void Append(StringBuilder css, string property, string value)
+	{
+		if (css.Length > 0) css.Append(';');
+		css.Append(property).Append(':').Append(value);
+	}
+}
diff --git a/MarkupString/Elements/CommandMenuMarkup.cs b/MarkupString/Elements/CommandMenuMarkup.cs
new file mode 100644
index 0000000..a83e67b
--- /dev/null
+++ b/MarkupString/Elements/CommandMenuMarkup.cs
@@ -0,0 +1,40 @@
+namespace MarkupString;
+
+/// <summary>One choice of a command menu.</summary>
+/// <param name="Label">What the menu shows.</param>
+/// <param name="Command">What choosing it sends.</param>
+public sealed record CommandChoice(string Label, string Command);
+
+/// <summary>
+/// Makes the text it wraps a menu of commands: a click sends the first, and a client with menus offers the rest.
+/// MXP writes it as <c>&lt;SEND href="a|b" hint="…|A|B"&gt;</c>.
+/// </summary>
+/// <param name="Choices">The commands, the default first.</param>
+/// <param name="Hint">A hint to show on hover, or null.</param>
+/// <param name="Prompt">Whether a click puts the command in the input line instead of sending it.</param>
+public sealed record CommandMenuMarkup(IReadOnlyList<CommandChoice> Choices, string? Hint = null, bool Prompt = false) : IMarkup
+{
+	/// <summary>Value equality, the choices compared item by item.</summary>
+	public bool Equals(CommandMenuMarkup? other) =>
+		other is not null
+		&& Prompt == other.Prompt
+		&& string.Equals(Hint, other.Hint, StringComparison.Ordinal)
+		&& Choices.SequenceEqual(other.Choices);
+
+	/// <inheritdoc/>
+	public override int GetHashCode()
+	{
+		var hash = new HashCode();
+		hash.Add(Hint, StringComparer.Ordinal);
+		hash.Add(Prompt);
+		foreach (var choice in Choices) hash.Add(choice);
+		return hash.ToHashCode();
+	}
+}
+
+/// <summary>
+/// Paints the background behind the text it wraps, as a search match or a selection is shown. Unlike a colour
+/// layer it says nothing about the text's own colour.
+/// </summary>
+/// <param name="Color">The background.</param>
+public sealed record HighlightMarkup(RgbColor Color) : IMarkup;
diff --git a/MarkupString/Elements/ElementCodecs.cs b/MarkupString/Elements/ElementCodecs.cs
index 76a62ae..c0ceb85 100644
--- a/MarkupString/Elements/ElementCodecs.cs
+++ b/MarkupString/Elements/ElementCodecs.cs
@@ -50,6 +50,7 @@ internal static class ElementCodecs
 					w.WriteNumber("rs", row.Rows);
 					w.WriteNumber("c", row.Columns);
 					if (row.IsDescription) w.WriteBoolean("dsc", true);
+					if (row.FirstColumn != 0) w.WriteNumber("fc", row.FirstColumn);
 				}
 			},
 			static e => new ImageMarkup(
@@ -60,7 +61,11 @@ internal static class ElementCodecs
 				Enum.TryParse<ImageAlign>(String(e, "a"), ignoreCase: true, out var align) ? align : null)
 			{
 				Row = Int(e, "r") is { } row && Int(e, "rs") is { } rows && Int(e, "c") is { } columns
-					? new PictureRow(row, rows, columns) { IsDescription = e.TryGetProperty("dsc", out var described) && described.ValueKind == JsonValueKind.True }
+					? new PictureRow(row, rows, columns)
+					{
+						IsDescription = e.TryGetProperty("dsc", out var described) && described.ValueKind == JsonValueKind.True,
+						FirstColumn = Int(e, "fc") ?? 0,
+					}
 					: null,
 			}),
 		new Codec<PaneMarkup>("pane",
@@ -113,6 +118,28 @@ internal static class ElementCodecs
 				if (m.Caption is not null) w.WriteString("ca", m.Caption);
 			},
 			static e => new StatusMarkup(String(e, "n") ?? string.Empty, String(e, "m"), String(e, "ca"))),
+		new Codec<CommandMenuMarkup>("menu",
+			static (w, m) =>
+			{
+				w.WriteStartArray("ch");
+				foreach (var choice in m.Choices)
+				{
+					w.WriteStartArray();
+					w.WriteStringValue(choice.Label);
+					w.WriteStringValue(choice.Command);
+					w.WriteEndArray();
+				}
+				w.WriteEndArray();
+				if (m.Hint is not null) w.WriteString("hi", m.Hint);
+				if (m.Prompt) w.WriteBoolean("p", true);
+			},
+			static e => new CommandMenuMarkup(
+				Choices(e),
+				String(e, "hi"),
+				e.TryGetProperty("p", out var p) && p.ValueKind == JsonValueKind.True)),
+		new Codec<HighlightMarkup>("highlight",
+			static (w, m) => w.WriteString("c", $"#{m.Color.R:x2}{m.Color.G:x2}{m.Color.B:x2}"),
+			static e => new HighlightMarkup(Hex(String(e, "c")))),
 		new Codec<StandInMarkup>("standin",
 			static (w, m) => w.WriteString("t", m.Text),
 			static e => new StandInMarkup(String(e, "t") ?? string.Empty)),
@@ -136,6 +163,27 @@ internal static class ElementCodecs
 			? number
 			: null;
 
+	private static CommandChoice[] Choices(JsonElement element)
+	{
+		if (!element.TryGetProperty("ch", out var array) || array.ValueKind != JsonValueKind.Array) return [];
+		var choices = new List<CommandChoice>(array.GetArrayLength());
+		foreach (var item in array.EnumerateArray())
+		{
+			if (item.ValueKind != JsonValueKind.Array || item.GetArrayLength() != 2) continue;
+			var label = item[0].ValueKind == JsonValueKind.String ? item[0].GetString() : null;
+			var command = item[1].ValueKind == JsonValueKind.String ? item[1].GetString() : null;
+			if (label is not null && command is not null) choices.Add(new CommandChoice(label, command));
+		}
+
+		return [.. choices];
+	}
+
+	private static RgbColor Hex(string? text) =>
+		text is { Length: 7 } && text[0] == '#'
+		&& int.TryParse(text.AsSpan(1), System.Globalization.NumberStyles.AllowHexSpecifier, System.Globalization.CultureInfo.InvariantCulture, out var value)
+			? new RgbColor((byte)(value >> 16), (byte)(value >> 8), (byte)value)
+			: default;
+
 	private static SoundChannel? Channel(JsonElement element) => String(element, "c") switch
 	{
 		"music" => SoundChannel.Music,
diff --git a/MarkupString/Elements/PictureRow.cs b/MarkupString/Elements/PictureRow.cs
index 0e0b0af..ca61d7e 100644
--- a/MarkupString/Elements/PictureRow.cs
+++ b/MarkupString/Elements/PictureRow.cs
@@ -23,4 +23,10 @@ public readonly record struct PictureRow(int Row, int Rows, int Columns)
 	/// description would be a strip.
 	/// </summary>
 	public bool IsDescription { get; init; }
+
+	/// <summary>
+	/// The column of the picture these cells start at, from 0. A placement that shows part of a picture (a Kitty
+	/// placement cropped by its placeholder text) starts past its left edge; a whole picture starts at 0.
+	/// </summary>
+	public int FirstColumn { get; init; }
 }
diff --git a/MarkupString/PublicAPI.Unshipped.txt b/MarkupString/PublicAPI.Unshipped.txt
index b94aa8b..8ba3d4f 100644
--- a/MarkupString/PublicAPI.Unshipped.txt
+++ b/MarkupString/PublicAPI.Unshipped.txt
@@ -29,3 +29,641 @@ MarkupString.ColorGradient.Roles.init -> void
 MarkupString.ColorGradient.Toned(System.Func<MarkupString.ThemeRole, MarkupString.IColorMarkup?>! tones) -> MarkupString.ColorGradient!
 MarkupString.Layout.LayoutContext.Tones.get -> System.Func<MarkupString.ThemeRole, MarkupString.IColorMarkup?>?
 MarkupString.Layout.LayoutContext.Tones.init -> void
+MarkupString.Decoding.ApcHandler
+MarkupString.Decoding.ClientAnswers
+MarkupString.Decoding.ClientAnswers.Colors = 4 -> MarkupString.Decoding.ClientAnswers
+MarkupString.Decoding.ClientAnswers.CursorPosition = 16 -> MarkupString.Decoding.ClientAnswers
+MarkupString.Decoding.ClientAnswers.Default = MarkupString.Decoding.ClientAnswers.Identity | MarkupString.Decoding.ClientAnswers.Size | MarkupString.Decoding.ClientAnswers.Colors | MarkupString.Decoding.ClientAnswers.Pictures | MarkupString.Decoding.ClientAnswers.Mxp -> MarkupString.Decoding.ClientAnswers
+MarkupString.Decoding.ClientAnswers.Identity = 1 -> MarkupString.Decoding.ClientAnswers
+MarkupString.Decoding.ClientAnswers.Mxp = 32 -> MarkupString.Decoding.ClientAnswers
+MarkupString.Decoding.ClientAnswers.None = 0 -> MarkupString.Decoding.ClientAnswers
+MarkupString.Decoding.ClientAnswers.Pictures = 8 -> MarkupString.Decoding.ClientAnswers
+MarkupString.Decoding.ClientAnswers.Size = 2 -> MarkupString.Decoding.ClientAnswers
+MarkupString.Decoding.ClientIdentity
+MarkupString.Decoding.ClientIdentity.<Clone>$() -> MarkupString.Decoding.ClientIdentity!
+MarkupString.Decoding.ClientIdentity.Answers.get -> MarkupString.Decoding.ClientAnswers
+MarkupString.Decoding.ClientIdentity.Answers.init -> void
+MarkupString.Decoding.ClientIdentity.Background.get -> MarkupString.RgbColor?
+MarkupString.Decoding.ClientIdentity.Background.init -> void
+MarkupString.Decoding.ClientIdentity.CellHeight.get -> int
+MarkupString.Decoding.ClientIdentity.CellHeight.init -> void
+MarkupString.Decoding.ClientIdentity.CellWidth.get -> int
+MarkupString.Decoding.ClientIdentity.CellWidth.init -> void
+MarkupString.Decoding.ClientIdentity.ClientIdentity() -> void
+MarkupString.Decoding.ClientIdentity.Columns.get -> int
+MarkupString.Decoding.ClientIdentity.Columns.init -> void
+MarkupString.Decoding.ClientIdentity.Equals(MarkupString.Decoding.ClientIdentity? other) -> bool
+MarkupString.Decoding.ClientIdentity.Foreground.get -> MarkupString.RgbColor?
+MarkupString.Decoding.ClientIdentity.Foreground.init -> void
+MarkupString.Decoding.ClientIdentity.Name.get -> string!
+MarkupString.Decoding.ClientIdentity.Name.init -> void
+MarkupString.Decoding.ClientIdentity.Output.get -> MarkupString.Display.OutputCapabilities!
+MarkupString.Decoding.ClientIdentity.Output.init -> void
+MarkupString.Decoding.ClientIdentity.Rows.get -> int
+MarkupString.Decoding.ClientIdentity.Rows.init -> void
+MarkupString.Decoding.ClientIdentity.ToMtts(bool screenReader = false, bool tls = false) -> MarkupString.Decoding.MttsFlags
+MarkupString.Decoding.ClientIdentity.Version.get -> string!
+MarkupString.Decoding.ClientIdentity.Version.init -> void
+MarkupString.Decoding.ClipboardEvent
+MarkupString.Decoding.ClipboardEvent.ClipboardEvent(string! Selection, string? Text) -> void
+MarkupString.Decoding.ClipboardEvent.Deconstruct(out string! Selection, out string? Text) -> void
+MarkupString.Decoding.ClipboardEvent.Equals(MarkupString.Decoding.ClipboardEvent? other) -> bool
+MarkupString.Decoding.ClipboardEvent.Selection.get -> string!
+MarkupString.Decoding.ClipboardEvent.Selection.init -> void
+MarkupString.Decoding.ClipboardEvent.Text.get -> string?
+MarkupString.Decoding.ClipboardEvent.Text.init -> void
+MarkupString.Decoding.ControlHandler
+MarkupString.Decoding.CsiHandler
+MarkupString.Decoding.CsiSequence
+MarkupString.Decoding.CsiSequence.Count.get -> int
+MarkupString.Decoding.CsiSequence.CsiSequence() -> void
+MarkupString.Decoding.CsiSequence.CsiSequence(char prefix, System.ReadOnlySpan<int> parameters, System.ReadOnlySpan<bool> subparameters, System.ReadOnlySpan<char> intermediates, char final) -> void
+MarkupString.Decoding.CsiSequence.Final.get -> char
+MarkupString.Decoding.CsiSequence.Get(int index, int fallback = 0) -> int
+MarkupString.Decoding.CsiSequence.Intermediates.get -> System.ReadOnlySpan<char>
+MarkupString.Decoding.CsiSequence.Is(char final, char prefix = '\0') -> bool
+MarkupString.Decoding.CsiSequence.IsSubparameter(int index) -> bool
+MarkupString.Decoding.CsiSequence.Parameters.get -> System.ReadOnlySpan<int>
+MarkupString.Decoding.CsiSequence.Prefix.get -> char
+MarkupString.Decoding.DcsHandler
+MarkupString.Decoding.DecodeContext
+MarkupString.Decoding.DecodeContext.Backspace(int cells = 1) -> void
+MarkupString.Decoding.DecodeContext.CarriageReturn() -> void
+MarkupString.Decoding.DecodeContext.Close(MarkupString.IMarkup! markup) -> bool
+MarkupString.Decoding.DecodeContext.CloseTo(int count) -> void
+MarkupString.Decoding.DecodeContext.Column.get -> int
+MarkupString.Decoding.DecodeContext.CurrentMarkup.get -> MarkupString.MarkupSet?
+MarkupString.Decoding.DecodeContext.Destination.get -> string?
+MarkupString.Decoding.DecodeContext.Destination.set -> void
+MarkupString.Decoding.DecodeContext.Diagnostics.get -> MarkupString.Decoding.DecodeDiagnostics!
+MarkupString.Decoding.DecodeContext.DisableProtocol(string! name) -> void
+MarkupString.Decoding.DecodeContext.Elements.get -> System.Collections.Generic.IReadOnlyList<MarkupString.IMarkup!>!
+MarkupString.Decoding.DecodeContext.EnableProtocol(string! name) -> bool
+MarkupString.Decoding.DecodeContext.EndLine() -> void
+MarkupString.Decoding.DecodeContext.EraseLine() -> void
+MarkupString.Decoding.DecodeContext.EraseToEndOfLine() -> void
+MarkupString.Decoding.DecodeContext.EraseToStartOfLine() -> void
+MarkupString.Decoding.DecodeContext.Identity.get -> MarkupString.Decoding.ClientIdentity!
+MarkupString.Decoding.DecodeContext.IsActive(string! name) -> bool
+MarkupString.Decoding.DecodeContext.MoveToColumn(int column) -> void
+MarkupString.Decoding.DecodeContext.Open(MarkupString.IMarkup! markup) -> bool
+MarkupString.Decoding.DecodeContext.Options.get -> MarkupString.Decoding.DecoderOptions!
+MarkupString.Decoding.DecodeContext.Pen(string! slot) -> MarkupString.IMarkup?
+MarkupString.Decoding.DecodeContext.PlacePicture(MarkupString.ImageMarkup! picture, int rows, int columns, bool cursorRight, int firstColumn = 0) -> void
+MarkupString.Decoding.DecodeContext.Point(MarkupString.IPointMarkup! point) -> void
+MarkupString.Decoding.DecodeContext.Print(System.ReadOnlySpan<char> text) -> void
+MarkupString.Decoding.DecodeContext.Raise(MarkupString.Decoding.DecodeEvent! decodeEvent) -> void
+MarkupString.Decoding.DecodeContext.Reply(string! text) -> void
+MarkupString.Decoding.DecodeContext.SetPen(string! slot, MarkupString.IMarkup? markup) -> void
+MarkupString.Decoding.DecodeContext.State<T>() -> T!
+MarkupString.Decoding.DecodeContext.Write(MarkupString.MarkupText! text) -> void
+MarkupString.Decoding.DecodeContext.Write(System.ReadOnlySpan<char> text) -> void
+MarkupString.Decoding.DecodeContext.Write(System.ReadOnlySpan<char> text, MarkupString.IMarkup? inner) -> void
+MarkupString.Decoding.DecodeDiagnostics
+MarkupString.Decoding.DecodeDiagnostics.AbandonedSequences.get -> int
+MarkupString.Decoding.DecodeDiagnostics.DecodeDiagnostics() -> void
+MarkupString.Decoding.DecodeDiagnostics.LimitsReached.get -> int
+MarkupString.Decoding.DecodeDiagnostics.PicturesFailed.get -> int
+MarkupString.Decoding.DecodeDiagnostics.UnhandledControls.get -> int
+MarkupString.Decoding.DecodeDiagnostics.UnhandledSequences.get -> int
+MarkupString.Decoding.DecodeEvent
+MarkupString.Decoding.DecodeEvent.DecodeEvent() -> void
+MarkupString.Decoding.DecodeEvent.DecodeEvent(MarkupString.Decoding.DecodeEvent! original) -> void
+MarkupString.Decoding.Decoder
+MarkupString.Decoding.Decoder.ActiveProtocol.get -> string?
+MarkupString.Decoding.Decoder.Diagnostics.get -> MarkupString.Decoding.DecodeDiagnostics!
+MarkupString.Decoding.Decoder.DisableProtocol(string! name) -> void
+MarkupString.Decoding.Decoder.EnableProtocol(string! name) -> bool
+MarkupString.Decoding.Decoder.EndLine() -> MarkupString.Decoding.DisplayLine!
+MarkupString.Decoding.Decoder.EndPrompt() -> MarkupString.Decoding.DisplayLine?
+MarkupString.Decoding.Decoder.EventRaised -> System.Action<MarkupString.Decoding.DecodeEvent!>?
+MarkupString.Decoding.Decoder.Feed(System.ReadOnlySpan<char> text) -> System.Collections.Generic.IReadOnlyList<MarkupString.Decoding.DisplayLine!>!
+MarkupString.Decoding.Decoder.Feed(string? text) -> System.Collections.Generic.IReadOnlyList<MarkupString.Decoding.DisplayLine!>!
+MarkupString.Decoding.Decoder.HasPendingLine.get -> bool
+MarkupString.Decoding.Decoder.Identity.get -> MarkupString.Decoding.ClientIdentity!
+MarkupString.Decoding.Decoder.Identity.set -> void
+MarkupString.Decoding.Decoder.Options.get -> MarkupString.Decoding.DecoderOptions!
+MarkupString.Decoding.Decoder.PendingLine.get -> MarkupString.MarkupText!
+MarkupString.Decoding.Decoder.Registry.get -> MarkupString.Decoding.DecoderRegistry!
+MarkupString.Decoding.Decoder.Reset() -> void
+MarkupString.Decoding.DecoderBuilder
+MarkupString.Decoding.DecoderBuilder.OnApc(MarkupString.Decoding.ApcHandler! handler) -> MarkupString.Decoding.DecoderBuilder!
+MarkupString.Decoding.DecoderBuilder.OnControl(char control, MarkupString.Decoding.ControlHandler! handler) -> MarkupString.Decoding.DecoderBuilder!
+MarkupString.Decoding.DecoderBuilder.OnCsi(char final, MarkupString.Decoding.CsiHandler! handler, char prefix = '\0', string! intermediates = "") -> MarkupString.Decoding.DecoderBuilder!
+MarkupString.Decoding.DecoderBuilder.OnDcs(char final, MarkupString.Decoding.DcsHandler! handler, char prefix = '\0', string! intermediates = "") -> MarkupString.Decoding.DecoderBuilder!
+MarkupString.Decoding.DecoderBuilder.OnEsc(char final, MarkupString.Decoding.EscHandler! handler, string! intermediates = "") -> MarkupString.Decoding.DecoderBuilder!
+MarkupString.Decoding.DecoderBuilder.OnLineEnd(System.Action<MarkupString.Decoding.DecodeContext!>! handler) -> MarkupString.Decoding.DecoderBuilder!
+MarkupString.Decoding.DecoderBuilder.OnOsc(int command, MarkupString.Decoding.OscHandler! handler) -> MarkupString.Decoding.DecoderBuilder!
+MarkupString.Decoding.DecoderBuilder.OnPrint(MarkupString.Decoding.PrintFilter! filter) -> MarkupString.Decoding.DecoderBuilder!
+MarkupString.Decoding.DecoderBuilder.TextProtocol(string! name, System.Func<MarkupString.Decoding.ITextProtocol!>! create) -> MarkupString.Decoding.DecoderBuilder!
+MarkupString.Decoding.DecoderOptions
+MarkupString.Decoding.DecoderOptions.<Clone>$() -> MarkupString.Decoding.DecoderOptions!
+MarkupString.Decoding.DecoderOptions.DecoderOptions() -> void
+MarkupString.Decoding.DecoderOptions.Equals(MarkupString.Decoding.DecoderOptions? other) -> bool
+MarkupString.Decoding.DecoderOptions.Identity.get -> MarkupString.Decoding.ClientIdentity!
+MarkupString.Decoding.DecoderOptions.Identity.init -> void
+MarkupString.Decoding.DecoderOptions.Limits.get -> MarkupString.Decoding.VtLimits!
+MarkupString.Decoding.DecoderOptions.Limits.init -> void
+MarkupString.Decoding.DecoderOptions.MaxLineLength.get -> int
+MarkupString.Decoding.DecoderOptions.MaxLineLength.init -> void
+MarkupString.Decoding.DecoderOptions.MaxOpenElements.get -> int
+MarkupString.Decoding.DecoderOptions.MaxOpenElements.init -> void
+MarkupString.Decoding.DecoderRegistry
+MarkupString.Decoding.DecoderRegistry.CreateDecoder(MarkupString.Decoding.DecoderOptions? options = null) -> MarkupString.Decoding.Decoder!
+MarkupString.Decoding.DecoderRegistry.Has(string! name) -> bool
+MarkupString.Decoding.DecoderRegistry.HasTextProtocol(string! name) -> bool
+MarkupString.Decoding.DecoderRegistry.Plugins.get -> System.Collections.Generic.IReadOnlyList<MarkupString.Decoding.IDecoderPlugin!>!
+MarkupString.Decoding.DecoderRegistry.With(MarkupString.Decoding.IDecoderPlugin! plugin) -> MarkupString.Decoding.DecoderRegistry!
+MarkupString.Decoding.DisplayLine
+MarkupString.Decoding.DisplayLine.<Clone>$() -> MarkupString.Decoding.DisplayLine!
+MarkupString.Decoding.DisplayLine.Content.get -> MarkupString.MarkupText!
+MarkupString.Decoding.DisplayLine.Content.init -> void
+MarkupString.Decoding.DisplayLine.Deconstruct(out MarkupString.MarkupText! Content, out MarkupString.Decoding.LineKind Kind) -> void
+MarkupString.Decoding.DisplayLine.Destination.get -> string?
+MarkupString.Decoding.DisplayLine.Destination.init -> void
+MarkupString.Decoding.DisplayLine.DisplayLine(MarkupString.MarkupText! Content, MarkupString.Decoding.LineKind Kind) -> void
+MarkupString.Decoding.DisplayLine.Equals(MarkupString.Decoding.DisplayLine? other) -> bool
+MarkupString.Decoding.DisplayLine.Kind.get -> MarkupString.Decoding.LineKind
+MarkupString.Decoding.DisplayLine.Kind.init -> void
+MarkupString.Decoding.DisplayLine.Sequence.get -> long
+MarkupString.Decoding.DisplayLine.Sequence.init -> void
+MarkupString.Decoding.DownloadEvent
+MarkupString.Decoding.DownloadEvent.Deconstruct(out string? Name, out int Size) -> void
+MarkupString.Decoding.DownloadEvent.DownloadEvent(string? Name, int Size) -> void
+MarkupString.Decoding.DownloadEvent.Equals(MarkupString.Decoding.DownloadEvent? other) -> bool
+MarkupString.Decoding.DownloadEvent.Name.get -> string?
+MarkupString.Decoding.DownloadEvent.Name.init -> void
+MarkupString.Decoding.DownloadEvent.Size.get -> int
+MarkupString.Decoding.DownloadEvent.Size.init -> void
+MarkupString.Decoding.EscHandler
+MarkupString.Decoding.EscSequence
+MarkupString.Decoding.EscSequence.EscSequence() -> void
+MarkupString.Decoding.EscSequence.EscSequence(System.ReadOnlySpan<char> intermediates, char final) -> void
+MarkupString.Decoding.EscSequence.Final.get -> char
+MarkupString.Decoding.EscSequence.Intermediates.get -> System.ReadOnlySpan<char>
+MarkupString.Decoding.IDecoderPlugin
+MarkupString.Decoding.IDecoderPlugin.Name.get -> string!
+MarkupString.Decoding.IDecoderPlugin.Register(MarkupString.Decoding.DecoderBuilder! builder) -> void
+MarkupString.Decoding.ITextProtocol
+MarkupString.Decoding.ITextProtocol.EndLine(MarkupString.Decoding.DecodeContext! context) -> void
+MarkupString.Decoding.ITextProtocol.Feed(System.ReadOnlySpan<char> text, MarkupString.Decoding.DecodeContext! context) -> void
+MarkupString.Decoding.ITextProtocol.Reset(MarkupString.Decoding.DecodeContext! context) -> void
+MarkupString.Decoding.IVtTokenSink
+MarkupString.Decoding.IVtTokenSink.Abandoned(MarkupString.Decoding.VtSequenceKind kind) -> void
+MarkupString.Decoding.IVtTokenSink.Apc(System.ReadOnlySpan<char> payload) -> void
+MarkupString.Decoding.IVtTokenSink.Csi(in MarkupString.Decoding.CsiSequence sequence) -> void
+MarkupString.Decoding.IVtTokenSink.Dcs(in MarkupString.Decoding.CsiSequence header, System.ReadOnlySpan<char> data) -> void
+MarkupString.Decoding.IVtTokenSink.Esc(in MarkupString.Decoding.EscSequence sequence) -> void
+MarkupString.Decoding.IVtTokenSink.Execute(char control) -> void
+MarkupString.Decoding.IVtTokenSink.Osc(System.ReadOnlySpan<char> payload) -> void
+MarkupString.Decoding.IVtTokenSink.Print(System.ReadOnlySpan<char> text) -> void
+MarkupString.Decoding.LineKind
+MarkupString.Decoding.LineKind.Output = 0 -> MarkupString.Decoding.LineKind
+MarkupString.Decoding.LineKind.Prompt = 1 -> MarkupString.Decoding.LineKind
+MarkupString.Decoding.MttsFlags
+MarkupString.Decoding.MttsFlags.Ansi = 1 -> MarkupString.Decoding.MttsFlags
+MarkupString.Decoding.MttsFlags.Colors256 = 8 -> MarkupString.Decoding.MttsFlags
+MarkupString.Decoding.MttsFlags.Mnes = 512 -> MarkupString.Decoding.MttsFlags
+MarkupString.Decoding.MttsFlags.MouseTracking = 16 -> MarkupString.Decoding.MttsFlags
+MarkupString.Decoding.MttsFlags.Mslp = 1024 -> MarkupString.Decoding.MttsFlags
+MarkupString.Decoding.MttsFlags.None = 0 -> MarkupString.Decoding.MttsFlags
+MarkupString.Decoding.MttsFlags.OscColorPalette = 32 -> MarkupString.Decoding.MttsFlags
+MarkupString.Decoding.MttsFlags.Proxy = 128 -> MarkupString.Decoding.MttsFlags
+MarkupString.Decoding.MttsFlags.ScreenReader = 64 -> MarkupString.Decoding.MttsFlags
+MarkupString.Decoding.MttsFlags.Ssl = 2048 -> MarkupString.Decoding.MttsFlags
+MarkupString.Decoding.MttsFlags.TrueColor = 256 -> MarkupString.Decoding.MttsFlags
+MarkupString.Decoding.MttsFlags.Utf8 = 4 -> MarkupString.Decoding.MttsFlags
+MarkupString.Decoding.MttsFlags.Vt100 = 2 -> MarkupString.Decoding.MttsFlags
+MarkupString.Decoding.OscHandler
+MarkupString.Decoding.PaletteEvent
+MarkupString.Decoding.PaletteEvent.Color.get -> MarkupString.RgbColor?
+MarkupString.Decoding.PaletteEvent.Color.init -> void
+MarkupString.Decoding.PaletteEvent.Deconstruct(out MarkupString.Decoding.PaletteSlot Slot, out int Index, out MarkupString.RgbColor? Color) -> void
+MarkupString.Decoding.PaletteEvent.Equals(MarkupString.Decoding.PaletteEvent? other) -> bool
+MarkupString.Decoding.PaletteEvent.Index.get -> int
+MarkupString.Decoding.PaletteEvent.Index.init -> void
+MarkupString.Decoding.PaletteEvent.PaletteEvent(MarkupString.Decoding.PaletteSlot Slot, int Index, MarkupString.RgbColor? Color) -> void
+MarkupString.Decoding.PaletteEvent.Slot.get -> MarkupString.Decoding.PaletteSlot
+MarkupString.Decoding.PaletteEvent.Slot.init -> void
+MarkupString.Decoding.PaletteSlot
+MarkupString.Decoding.PaletteSlot.Background = 2 -> MarkupString.Decoding.PaletteSlot
+MarkupString.Decoding.PaletteSlot.Cursor = 3 -> MarkupString.Decoding.PaletteSlot
+MarkupString.Decoding.PaletteSlot.Foreground = 1 -> MarkupString.Decoding.PaletteSlot
+MarkupString.Decoding.PaletteSlot.Index = 0 -> MarkupString.Decoding.PaletteSlot
+MarkupString.Decoding.PrintFilter
+MarkupString.Decoding.ProtocolEvent
+MarkupString.Decoding.ProtocolEvent.Active.get -> bool
+MarkupString.Decoding.ProtocolEvent.Active.init -> void
+MarkupString.Decoding.ProtocolEvent.Deconstruct(out string! Name, out bool Active) -> void
+MarkupString.Decoding.ProtocolEvent.Equals(MarkupString.Decoding.ProtocolEvent? other) -> bool
+MarkupString.Decoding.ProtocolEvent.Name.get -> string!
+MarkupString.Decoding.ProtocolEvent.Name.init -> void
+MarkupString.Decoding.ProtocolEvent.ProtocolEvent(string! Name, bool Active) -> void
+MarkupString.Decoding.ReplyEvent
+MarkupString.Decoding.ReplyEvent.Deconstruct(out string! Text) -> void
+MarkupString.Decoding.ReplyEvent.Equals(MarkupString.Decoding.ReplyEvent? other) -> bool
+MarkupString.Decoding.ReplyEvent.ReplyEvent(string! Text) -> void
+MarkupString.Decoding.ReplyEvent.Text.get -> string!
+MarkupString.Decoding.ReplyEvent.Text.init -> void
+MarkupString.Decoding.TitleEvent
+MarkupString.Decoding.TitleEvent.Deconstruct(out string! Title, out bool Icon) -> void
+MarkupString.Decoding.TitleEvent.Equals(MarkupString.Decoding.TitleEvent? other) -> bool
+MarkupString.Decoding.TitleEvent.Icon.get -> bool
+MarkupString.Decoding.TitleEvent.Icon.init -> void
+MarkupString.Decoding.TitleEvent.Title.get -> string!
+MarkupString.Decoding.TitleEvent.Title.init -> void
+MarkupString.Decoding.TitleEvent.TitleEvent(string! Title, bool Icon) -> void
+MarkupString.Decoding.VariableEvent
+MarkupString.Decoding.VariableEvent.Deconstruct(out string! Name, out string? Value) -> void
+MarkupString.Decoding.VariableEvent.Equals(MarkupString.Decoding.VariableEvent? other) -> bool
+MarkupString.Decoding.VariableEvent.Name.get -> string!
+MarkupString.Decoding.VariableEvent.Name.init -> void
+MarkupString.Decoding.VariableEvent.Value.get -> string?
+MarkupString.Decoding.VariableEvent.Value.init -> void
+MarkupString.Decoding.VariableEvent.VariableEvent(string! Name, string? Value) -> void
+MarkupString.Decoding.VtLimits
+MarkupString.Decoding.VtLimits.<Clone>$() -> MarkupString.Decoding.VtLimits!
+MarkupString.Decoding.VtLimits.Equals(MarkupString.Decoding.VtLimits? other) -> bool
+MarkupString.Decoding.VtLimits.MaxApcLength.get -> int
+MarkupString.Decoding.VtLimits.MaxApcLength.init -> void
+MarkupString.Decoding.VtLimits.MaxParameterValue.get -> int
+MarkupString.Decoding.VtLimits.MaxParameterValue.init -> void
+MarkupString.Decoding.VtLimits.MaxParameters.get -> int
+MarkupString.Decoding.VtLimits.MaxParameters.init -> void
+MarkupString.Decoding.VtLimits.MaxStringLength.get -> int
+MarkupString.Decoding.VtLimits.MaxStringLength.init -> void
+MarkupString.Decoding.VtLimits.VtLimits() -> void
+MarkupString.Decoding.VtSequenceKind
+MarkupString.Decoding.VtSequenceKind.Apc = 4 -> MarkupString.Decoding.VtSequenceKind
+MarkupString.Decoding.VtSequenceKind.Csi = 1 -> MarkupString.Decoding.VtSequenceKind
+MarkupString.Decoding.VtSequenceKind.Dcs = 3 -> MarkupString.Decoding.VtSequenceKind
+MarkupString.Decoding.VtSequenceKind.Escape = 0 -> MarkupString.Decoding.VtSequenceKind
+MarkupString.Decoding.VtSequenceKind.Osc = 2 -> MarkupString.Decoding.VtSequenceKind
+MarkupString.Decoding.VtTokenizer
+MarkupString.Decoding.VtTokenizer.Feed(System.ReadOnlySpan<char> text, MarkupString.Decoding.IVtTokenSink! sink) -> void
+MarkupString.Decoding.VtTokenizer.InSequence.get -> bool
+MarkupString.Decoding.VtTokenizer.Interrupt(MarkupString.Decoding.IVtTokenSink! sink) -> void
+MarkupString.Decoding.VtTokenizer.Reset() -> void
+MarkupString.Decoding.VtTokenizer.VtTokenizer() -> void
+MarkupString.Decoding.VtTokenizer.VtTokenizer(MarkupString.Decoding.VtLimits! limits) -> void
+MarkupString.Display.ColorLevel
+MarkupString.Display.ColorLevel.Attributes = 1 -> MarkupString.Display.ColorLevel
+MarkupString.Display.ColorLevel.None = 0 -> MarkupString.Display.ColorLevel
+MarkupString.Display.ColorLevel.Standard = 2 -> MarkupString.Display.ColorLevel
+MarkupString.Display.ColorLevel.TrueColor = 4 -> MarkupString.Display.ColorLevel
+MarkupString.Display.ColorLevel.Xterm256 = 3 -> MarkupString.Display.ColorLevel
+MarkupString.Display.InteractionKinds
+MarkupString.Display.InteractionKinds.All = MarkupString.Display.InteractionKinds.Url | MarkupString.Display.InteractionKinds.Command | MarkupString.Display.InteractionKinds.Prompt | MarkupString.Display.InteractionKinds.Menu -> MarkupString.Display.InteractionKinds
+MarkupString.Display.InteractionKinds.Command = 2 -> MarkupString.Display.InteractionKinds
+MarkupString.Display.InteractionKinds.Menu = 8 -> MarkupString.Display.InteractionKinds
+MarkupString.Display.InteractionKinds.None = 0 -> MarkupString.Display.InteractionKinds
+MarkupString.Display.InteractionKinds.Prompt = 4 -> MarkupString.Display.InteractionKinds
+MarkupString.Display.InteractionKinds.Url = 1 -> MarkupString.Display.InteractionKinds
+MarkupString.Display.OutputCapabilities
+MarkupString.Display.OutputCapabilities.<Clone>$() -> MarkupString.Display.OutputCapabilities!
+MarkupString.Display.OutputCapabilities.Attributes.get -> MarkupString.Display.TextAttributes
+MarkupString.Display.OutputCapabilities.Attributes.init -> void
+MarkupString.Display.OutputCapabilities.BestPictureMethod.get -> MarkupString.Display.PictureMethods
+MarkupString.Display.OutputCapabilities.Colors.get -> MarkupString.Display.ColorLevel
+MarkupString.Display.OutputCapabilities.Colors.init -> void
+MarkupString.Display.OutputCapabilities.Equals(MarkupString.Display.OutputCapabilities? other) -> bool
+MarkupString.Display.OutputCapabilities.Interactions.get -> MarkupString.Display.InteractionKinds
+MarkupString.Display.OutputCapabilities.Interactions.init -> void
+MarkupString.Display.OutputCapabilities.Intersect(MarkupString.Display.OutputCapabilities! other) -> MarkupString.Display.OutputCapabilities!
+MarkupString.Display.OutputCapabilities.MovingPictures.get -> bool
+MarkupString.Display.OutputCapabilities.MovingPictures.init -> void
+MarkupString.Display.OutputCapabilities.OutputCapabilities() -> void
+MarkupString.Display.OutputCapabilities.Panes.get -> bool
+MarkupString.Display.OutputCapabilities.Panes.init -> void
+MarkupString.Display.OutputCapabilities.Pictures.get -> MarkupString.Display.PictureMethods
+MarkupString.Display.OutputCapabilities.Pictures.init -> void
+MarkupString.Display.OutputCapabilities.Sound.get -> bool
+MarkupString.Display.OutputCapabilities.Sound.init -> void
+MarkupString.Display.OutputCapabilities.Unicode.get -> MarkupString.Display.UnicodeLevel
+MarkupString.Display.OutputCapabilities.Unicode.init -> void
+MarkupString.Display.OutputCapabilities.Union(MarkupString.Display.OutputCapabilities! other) -> MarkupString.Display.OutputCapabilities!
+MarkupString.Display.PictureMethods
+MarkupString.Display.PictureMethods.Bitmap = 1 -> MarkupString.Display.PictureMethods
+MarkupString.Display.PictureMethods.HalfBlocks = 16 -> MarkupString.Display.PictureMethods
+MarkupString.Display.PictureMethods.InlineImages = 4 -> MarkupString.Display.PictureMethods
+MarkupString.Display.PictureMethods.KittyPlaceholders = 2 -> MarkupString.Display.PictureMethods
+MarkupString.Display.PictureMethods.None = 0 -> MarkupString.Display.PictureMethods
+MarkupString.Display.PictureMethods.Sixel = 8 -> MarkupString.Display.PictureMethods
+MarkupString.Display.TextAttributes
+MarkupString.Display.TextAttributes.All = MarkupString.Display.TextAttributes.Bold | MarkupString.Display.TextAttributes.Faint | MarkupString.Display.TextAttributes.Italic | MarkupString.Display.TextAttributes.Underline | MarkupString.Display.TextAttributes.Blink | MarkupString.Display.TextAttributes.Inverse | MarkupString.Display.TextAttributes.Conceal | MarkupString.Display.TextAttributes.Strikethrough | MarkupString.Display.TextAttributes.Overline -> MarkupString.Display.TextAttributes
+MarkupString.Display.TextAttributes.Blink = 16 -> MarkupString.Display.TextAttributes
+MarkupString.Display.TextAttributes.Bold = 1 -> MarkupString.Display.TextAttributes
+MarkupString.Display.TextAttributes.Conceal = 64 -> MarkupString.Display.TextAttributes
+MarkupString.Display.TextAttributes.Faint = 2 -> MarkupString.Display.TextAttributes
+MarkupString.Display.TextAttributes.Inverse = 32 -> MarkupString.Display.TextAttributes
+MarkupString.Display.TextAttributes.Italic = 4 -> MarkupString.Display.TextAttributes
+MarkupString.Display.TextAttributes.None = 0 -> MarkupString.Display.TextAttributes
+MarkupString.Display.TextAttributes.Overline = 256 -> MarkupString.Display.TextAttributes
+MarkupString.Display.TextAttributes.Strikethrough = 128 -> MarkupString.Display.TextAttributes
+MarkupString.Display.TextAttributes.Underline = 8 -> MarkupString.Display.TextAttributes
+MarkupString.Display.UnicodeLevel
+MarkupString.Display.UnicodeLevel.Ascii = 2 -> MarkupString.Display.UnicodeLevel
+MarkupString.Display.UnicodeLevel.Full = 0 -> MarkupString.Display.UnicodeLevel
+MarkupString.Display.UnicodeLevel.Narrow = 1 -> MarkupString.Display.UnicodeLevel
+MarkupString.PictureRow.FirstColumn.get -> int
+MarkupString.PictureRow.FirstColumn.init -> void
+abstract MarkupString.Decoding.DecodeEvent.<Clone>$() -> MarkupString.Decoding.DecodeEvent!
+const MarkupString.Decoding.CsiSequence.Omitted = -1 -> int
+override MarkupString.Decoding.ClientIdentity.Equals(object? obj) -> bool
+override MarkupString.Decoding.ClientIdentity.GetHashCode() -> int
+override MarkupString.Decoding.ClientIdentity.ToString() -> string!
+override MarkupString.Decoding.ClipboardEvent.<Clone>$() -> MarkupString.Decoding.ClipboardEvent!
+override MarkupString.Decoding.ClipboardEvent.Equals(object? obj) -> bool
+override MarkupString.Decoding.ClipboardEvent.GetHashCode() -> int
+override MarkupString.Decoding.ClipboardEvent.ToString() -> string!
+override MarkupString.Decoding.DecodeEvent.Equals(object? obj) -> bool
+override MarkupString.Decoding.DecodeEvent.GetHashCode() -> int
+override MarkupString.Decoding.DecodeEvent.ToString() -> string!
+override MarkupString.Decoding.DecoderOptions.Equals(object? obj) -> bool
+override MarkupString.Decoding.DecoderOptions.GetHashCode() -> int
+override MarkupString.Decoding.DecoderOptions.ToString() -> string!
+override MarkupString.Decoding.DisplayLine.Equals(object? obj) -> bool
+override MarkupString.Decoding.DisplayLine.GetHashCode() -> int
+override MarkupString.Decoding.DisplayLine.ToString() -> string!
+override MarkupString.Decoding.DownloadEvent.<Clone>$() -> MarkupString.Decoding.DownloadEvent!
+override MarkupString.Decoding.DownloadEvent.Equals(object? obj) -> bool
+override MarkupString.Decoding.DownloadEvent.GetHashCode() -> int
+override MarkupString.Decoding.DownloadEvent.ToString() -> string!
+override MarkupString.Decoding.PaletteEvent.<Clone>$() -> MarkupString.Decoding.PaletteEvent!
+override MarkupString.Decoding.PaletteEvent.Equals(object? obj) -> bool
+override MarkupString.Decoding.PaletteEvent.GetHashCode() -> int
+override MarkupString.Decoding.PaletteEvent.ToString() -> string!
+override MarkupString.Decoding.ProtocolEvent.<Clone>$() -> MarkupString.Decoding.ProtocolEvent!
+override MarkupString.Decoding.ProtocolEvent.Equals(object? obj) -> bool
+override MarkupString.Decoding.ProtocolEvent.GetHashCode() -> int
+override MarkupString.Decoding.ProtocolEvent.ToString() -> string!
+override MarkupString.Decoding.ReplyEvent.<Clone>$() -> MarkupString.Decoding.ReplyEvent!
+override MarkupString.Decoding.ReplyEvent.Equals(object? obj) -> bool
+override MarkupString.Decoding.ReplyEvent.GetHashCode() -> int
+override MarkupString.Decoding.ReplyEvent.ToString() -> string!
+override MarkupString.Decoding.TitleEvent.<Clone>$() -> MarkupString.Decoding.TitleEvent!
+override MarkupString.Decoding.TitleEvent.Equals(object? obj) -> bool
+override MarkupString.Decoding.TitleEvent.GetHashCode() -> int
+override MarkupString.Decoding.TitleEvent.ToString() -> string!
+override MarkupString.Decoding.VariableEvent.<Clone>$() -> MarkupString.Decoding.VariableEvent!
+override MarkupString.Decoding.VariableEvent.Equals(object? obj) -> bool
+override MarkupString.Decoding.VariableEvent.GetHashCode() -> int
+override MarkupString.Decoding.VariableEvent.ToString() -> string!
+override MarkupString.Decoding.VtLimits.Equals(object? obj) -> bool
+override MarkupString.Decoding.VtLimits.GetHashCode() -> int
+override MarkupString.Decoding.VtLimits.ToString() -> string!
+override MarkupString.Display.OutputCapabilities.Equals(object? obj) -> bool
+override MarkupString.Display.OutputCapabilities.GetHashCode() -> int
+override MarkupString.Display.OutputCapabilities.ToString() -> string!
+override sealed MarkupString.Decoding.ClipboardEvent.Equals(MarkupString.Decoding.DecodeEvent? other) -> bool
+override sealed MarkupString.Decoding.DownloadEvent.Equals(MarkupString.Decoding.DecodeEvent? other) -> bool
+override sealed MarkupString.Decoding.PaletteEvent.Equals(MarkupString.Decoding.DecodeEvent? other) -> bool
+override sealed MarkupString.Decoding.ProtocolEvent.Equals(MarkupString.Decoding.DecodeEvent? other) -> bool
+override sealed MarkupString.Decoding.ReplyEvent.Equals(MarkupString.Decoding.DecodeEvent? other) -> bool
+override sealed MarkupString.Decoding.TitleEvent.Equals(MarkupString.Decoding.DecodeEvent? other) -> bool
+override sealed MarkupString.Decoding.VariableEvent.Equals(MarkupString.Decoding.DecodeEvent? other) -> bool
+static MarkupString.Decoding.ClientIdentity.operator !=(MarkupString.Decoding.ClientIdentity? left, MarkupString.Decoding.ClientIdentity? right) -> bool
+static MarkupString.Decoding.ClientIdentity.operator ==(MarkupString.Decoding.ClientIdentity? left, MarkupString.Decoding.ClientIdentity? right) -> bool
+static MarkupString.Decoding.ClipboardEvent.operator !=(MarkupString.Decoding.ClipboardEvent? left, MarkupString.Decoding.ClipboardEvent? right) -> bool
+static MarkupString.Decoding.ClipboardEvent.operator ==(MarkupString.Decoding.ClipboardEvent? left, MarkupString.Decoding.ClipboardEvent? right) -> bool
+static MarkupString.Decoding.DecodeEvent.operator !=(MarkupString.Decoding.DecodeEvent? left, MarkupString.Decoding.DecodeEvent? right) -> bool
+static MarkupString.Decoding.DecodeEvent.operator ==(MarkupString.Decoding.DecodeEvent? left, MarkupString.Decoding.DecodeEvent? right) -> bool
+static MarkupString.Decoding.Decoder.DecodeAll(string? text, MarkupString.Decoding.DecoderRegistry! registry, MarkupString.Decoding.DecoderOptions? options = null) -> System.Collections.Generic.IReadOnlyList<MarkupString.Decoding.DisplayLine!>!
+static MarkupString.Decoding.DecoderOptions.operator !=(MarkupString.Decoding.DecoderOptions? left, MarkupString.Decoding.DecoderOptions? right) -> bool
+static MarkupString.Decoding.DecoderOptions.operator ==(MarkupString.Decoding.DecoderOptions? left, MarkupString.Decoding.DecoderOptions? right) -> bool
+static MarkupString.Decoding.DecoderRegistry.Empty.get -> MarkupString.Decoding.DecoderRegistry!
+static MarkupString.Decoding.DisplayLine.operator !=(MarkupString.Decoding.DisplayLine? left, MarkupString.Decoding.DisplayLine? right) -> bool
+static MarkupString.Decoding.DisplayLine.operator ==(MarkupString.Decoding.DisplayLine? left, MarkupString.Decoding.DisplayLine? right) -> bool
+static MarkupString.Decoding.DownloadEvent.operator !=(MarkupString.Decoding.DownloadEvent? left, MarkupString.Decoding.DownloadEvent? right) -> bool
+static MarkupString.Decoding.DownloadEvent.operator ==(MarkupString.Decoding.DownloadEvent? left, MarkupString.Decoding.DownloadEvent? right) -> bool
+static MarkupString.Decoding.PaletteEvent.operator !=(MarkupString.Decoding.PaletteEvent? left, MarkupString.Decoding.PaletteEvent? right) -> bool
+static MarkupString.Decoding.PaletteEvent.operator ==(MarkupString.Decoding.PaletteEvent? left, MarkupString.Decoding.PaletteEvent? right) -> bool
+static MarkupString.Decoding.ProtocolEvent.operator !=(MarkupString.Decoding.ProtocolEvent? left, MarkupString.Decoding.ProtocolEvent? right) -> bool
+static MarkupString.Decoding.ProtocolEvent.operator ==(MarkupString.Decoding.ProtocolEvent? left, MarkupString.Decoding.ProtocolEvent? right) -> bool
+static MarkupString.Decoding.ReplyEvent.operator !=(MarkupString.Decoding.ReplyEvent? left, MarkupString.Decoding.ReplyEvent? right) -> bool
+static MarkupString.Decoding.ReplyEvent.operator ==(MarkupString.Decoding.ReplyEvent? left, MarkupString.Decoding.ReplyEvent? right) -> bool
+static MarkupString.Decoding.TitleEvent.operator !=(MarkupString.Decoding.TitleEvent? left, MarkupString.Decoding.TitleEvent? right) -> bool
+static MarkupString.Decoding.TitleEvent.operator ==(MarkupString.Decoding.TitleEvent? left, MarkupString.Decoding.TitleEvent? right) -> bool
+static MarkupString.Decoding.VariableEvent.operator !=(MarkupString.Decoding.VariableEvent? left, MarkupString.Decoding.VariableEvent? right) -> bool
+static MarkupString.Decoding.VariableEvent.operator ==(MarkupString.Decoding.VariableEvent? left, MarkupString.Decoding.VariableEvent? right) -> bool
+static MarkupString.Decoding.VtLimits.Default.get -> MarkupString.Decoding.VtLimits!
+static MarkupString.Decoding.VtLimits.operator !=(MarkupString.Decoding.VtLimits? left, MarkupString.Decoding.VtLimits? right) -> bool
+static MarkupString.Decoding.VtLimits.operator ==(MarkupString.Decoding.VtLimits? left, MarkupString.Decoding.VtLimits? right) -> bool
+static MarkupString.Display.OutputCapabilities.Browser.get -> MarkupString.Display.OutputCapabilities!
+static MarkupString.Display.OutputCapabilities.CellGrid.get -> MarkupString.Display.OutputCapabilities!
+static MarkupString.Display.OutputCapabilities.PlainText.get -> MarkupString.Display.OutputCapabilities!
+static MarkupString.Display.OutputCapabilities.operator !=(MarkupString.Display.OutputCapabilities? left, MarkupString.Display.OutputCapabilities? right) -> bool
+static MarkupString.Display.OutputCapabilities.operator ==(MarkupString.Display.OutputCapabilities? left, MarkupString.Display.OutputCapabilities? right) -> bool
+virtual MarkupString.Decoding.ApcHandler.Invoke(System.ReadOnlySpan<char> payload, MarkupString.Decoding.DecodeContext! context) -> bool
+virtual MarkupString.Decoding.ControlHandler.Invoke(char control, MarkupString.Decoding.DecodeContext! context) -> bool
+virtual MarkupString.Decoding.CsiHandler.Invoke(in MarkupString.Decoding.CsiSequence sequence, MarkupString.Decoding.DecodeContext! context) -> bool
+virtual MarkupString.Decoding.DcsHandler.Invoke(in MarkupString.Decoding.CsiSequence header, System.ReadOnlySpan<char> data, MarkupString.Decoding.DecodeContext! context) -> bool
+virtual MarkupString.Decoding.DecodeEvent.EqualityContract.get -> System.Type!
+virtual MarkupString.Decoding.DecodeEvent.Equals(MarkupString.Decoding.DecodeEvent? other) -> bool
+virtual MarkupString.Decoding.DecodeEvent.PrintMembers(System.Text.StringBuilder! builder) -> bool
+virtual MarkupString.Decoding.EscHandler.Invoke(in MarkupString.Decoding.EscSequence sequence, MarkupString.Decoding.DecodeContext! context) -> bool
+virtual MarkupString.Decoding.OscHandler.Invoke(System.ReadOnlySpan<char> payload, MarkupString.Decoding.DecodeContext! context) -> bool
+virtual MarkupString.Decoding.PrintFilter.Invoke(System.ReadOnlySpan<char> text, MarkupString.Decoding.DecodeContext! context) -> bool
+MarkupString.CommandChoice
+MarkupString.CommandChoice.<Clone>$() -> MarkupString.CommandChoice!
+MarkupString.CommandChoice.Command.get -> string!
+MarkupString.CommandChoice.Command.init -> void
+MarkupString.CommandChoice.CommandChoice(string! Label, string! Command) -> void
+MarkupString.CommandChoice.Deconstruct(out string! Label, out string! Command) -> void
+MarkupString.CommandChoice.Equals(MarkupString.CommandChoice? other) -> bool
+MarkupString.CommandChoice.Label.get -> string!
+MarkupString.CommandChoice.Label.init -> void
+MarkupString.CommandMenuMarkup
+MarkupString.CommandMenuMarkup.<Clone>$() -> MarkupString.CommandMenuMarkup!
+MarkupString.CommandMenuMarkup.Choices.get -> System.Collections.Generic.IReadOnlyList<MarkupString.CommandChoice!>!
+MarkupString.CommandMenuMarkup.Choices.init -> void
+MarkupString.CommandMenuMarkup.CommandMenuMarkup(System.Collections.Generic.IReadOnlyList<MarkupString.CommandChoice!>! Choices, string? Hint = null, bool Prompt = false) -> void
+MarkupString.CommandMenuMarkup.Deconstruct(out System.Collections.Generic.IReadOnlyList<MarkupString.CommandChoice!>! Choices, out string? Hint, out bool Prompt) -> void
+MarkupString.CommandMenuMarkup.Equals(MarkupString.CommandMenuMarkup? other) -> bool
+MarkupString.CommandMenuMarkup.Hint.get -> string?
+MarkupString.CommandMenuMarkup.Hint.init -> void
+MarkupString.CommandMenuMarkup.Prompt.get -> bool
+MarkupString.CommandMenuMarkup.Prompt.init -> void
+MarkupString.Display.Cell
+MarkupString.Display.Cell.Cell() -> void
+MarkupString.Display.Cell.Cell(string! Text, MarkupString.Display.DisplayStyle Style) -> void
+MarkupString.Display.Cell.Deconstruct(out string! Text, out MarkupString.Display.DisplayStyle Style) -> void
+MarkupString.Display.Cell.Equals(MarkupString.Display.Cell other) -> bool
+MarkupString.Display.Cell.IsContinuation.get -> bool
+MarkupString.Display.Cell.PictureColumn.get -> int
+MarkupString.Display.Cell.PictureColumn.init -> void
+MarkupString.Display.Cell.Style.get -> MarkupString.Display.DisplayStyle
+MarkupString.Display.Cell.Style.init -> void
+MarkupString.Display.Cell.Text.get -> string!
+MarkupString.Display.Cell.Text.init -> void
+MarkupString.Display.Cell.Width.get -> int
+MarkupString.Display.Cell.Width.init -> void
+MarkupString.Display.CellLayout
+MarkupString.Display.CellLayout.At(int row, int column) -> MarkupString.Display.Cell?
+MarkupString.Display.CellLayout.Columns.get -> int
+MarkupString.Display.CellLayout.InteractionAt(int row, int column) -> MarkupString.Display.Interaction?
+MarkupString.Display.CellLayout.Points.get -> System.Collections.Generic.IReadOnlyList<MarkupString.Display.CellPoint>!
+MarkupString.Display.CellLayout.Rows.get -> System.Collections.Generic.IReadOnlyList<MarkupString.Display.CellRow!>!
+MarkupString.Display.CellPoint
+MarkupString.Display.CellPoint.CellPoint() -> void
+MarkupString.Display.CellPoint.CellPoint(int Row, int Column, MarkupString.IPointMarkup! Markup) -> void
+MarkupString.Display.CellPoint.Column.get -> int
+MarkupString.Display.CellPoint.Column.init -> void
+MarkupString.Display.CellPoint.Deconstruct(out int Row, out int Column, out MarkupString.IPointMarkup! Markup) -> void
+MarkupString.Display.CellPoint.Equals(MarkupString.Display.CellPoint other) -> bool
+MarkupString.Display.CellPoint.Markup.get -> MarkupString.IPointMarkup!
+MarkupString.Display.CellPoint.Markup.init -> void
+MarkupString.Display.CellPoint.Row.get -> int
+MarkupString.Display.CellPoint.Row.init -> void
+MarkupString.Display.CellRenderer
+MarkupString.Display.CellRow
+MarkupString.Display.CellRow.Cells.get -> System.Collections.Generic.IReadOnlyList<MarkupString.Display.Cell>!
+MarkupString.Display.CellRow.Wrapped.get -> bool
+MarkupString.Display.DisplayOptions
+MarkupString.Display.DisplayOptions.<Clone>$() -> MarkupString.Display.DisplayOptions!
+MarkupString.Display.DisplayOptions.Capabilities.get -> MarkupString.Display.OutputCapabilities!
+MarkupString.Display.DisplayOptions.Capabilities.init -> void
+MarkupString.Display.DisplayOptions.Colors.get -> MarkupString.Display.IColorResolver?
+MarkupString.Display.DisplayOptions.Colors.init -> void
+MarkupString.Display.DisplayOptions.DefaultBackground.get -> MarkupString.RgbColor
+MarkupString.Display.DisplayOptions.DefaultBackground.init -> void
+MarkupString.Display.DisplayOptions.DefaultForeground.get -> MarkupString.RgbColor
+MarkupString.Display.DisplayOptions.DefaultForeground.init -> void
+MarkupString.Display.DisplayOptions.DisplayOptions() -> void
+MarkupString.Display.DisplayOptions.Equals(MarkupString.Display.DisplayOptions? other) -> bool
+MarkupString.Display.DisplayOptions.TabWidth.get -> int
+MarkupString.Display.DisplayOptions.TabWidth.init -> void
+MarkupString.Display.DisplayRegistry
+MarkupString.Display.DisplayRegistry.Contributors.get -> System.Collections.Generic.IReadOnlyList<MarkupString.Display.IStyleContributor!>!
+MarkupString.Display.DisplayRegistry.Resolve(MarkupString.MarkupSet? markups, MarkupString.Display.DisplayOptions! options) -> MarkupString.Display.DisplayStyle
+MarkupString.Display.DisplayRegistry.With(MarkupString.Display.IStyleContributor! contributor) -> MarkupString.Display.DisplayRegistry!
+MarkupString.Display.DisplaySpan
+MarkupString.Display.DisplaySpan.Deconstruct(out string! Text, out MarkupString.Display.DisplayStyle Style) -> void
+MarkupString.Display.DisplaySpan.DisplaySpan() -> void
+MarkupString.Display.DisplaySpan.DisplaySpan(string! Text, MarkupString.Display.DisplayStyle Style) -> void
+MarkupString.Display.DisplaySpan.Equals(MarkupString.Display.DisplaySpan other) -> bool
+MarkupString.Display.DisplaySpan.Point.get -> MarkupString.IPointMarkup?
+MarkupString.Display.DisplaySpan.Point.init -> void
+MarkupString.Display.DisplaySpan.Style.get -> MarkupString.Display.DisplayStyle
+MarkupString.Display.DisplaySpan.Style.init -> void
+MarkupString.Display.DisplaySpan.Text.get -> string!
+MarkupString.Display.DisplaySpan.Text.init -> void
+MarkupString.Display.DisplayStyle
+MarkupString.Display.DisplayStyle.Attributes.get -> MarkupString.Display.TextAttributes
+MarkupString.Display.DisplayStyle.Attributes.init -> void
+MarkupString.Display.DisplayStyle.Background.get -> MarkupString.RgbColor?
+MarkupString.Display.DisplayStyle.Background.init -> void
+MarkupString.Display.DisplayStyle.DisplayStyle() -> void
+MarkupString.Display.DisplayStyle.Equals(MarkupString.Display.DisplayStyle other) -> bool
+MarkupString.Display.DisplayStyle.Foreground.get -> MarkupString.RgbColor?
+MarkupString.Display.DisplayStyle.Foreground.init -> void
+MarkupString.Display.DisplayStyle.Has(MarkupString.Display.TextAttributes attribute) -> bool
+MarkupString.Display.DisplayStyle.Interaction.get -> MarkupString.Display.Interaction?
+MarkupString.Display.DisplayStyle.Interaction.init -> void
+MarkupString.Display.DisplayStyle.Pane.get -> string?
+MarkupString.Display.DisplayStyle.Pane.init -> void
+MarkupString.Display.DisplayStyle.Picture.get -> MarkupString.ImageMarkup?
+MarkupString.Display.DisplayStyle.Picture.init -> void
+MarkupString.Display.IColorResolver
+MarkupString.Display.IColorResolver.Legible(MarkupString.RgbColor foreground, MarkupString.RgbColor background) -> MarkupString.RgbColor
+MarkupString.Display.IColorResolver.Standard(int index, bool bright) -> MarkupString.RgbColor
+MarkupString.Display.IColorResolver.Xterm(int index) -> MarkupString.RgbColor
+MarkupString.Display.IStyleContributor
+MarkupString.Display.IStyleContributor.Contribute(MarkupString.MarkupSet! markups, MarkupString.Display.StyleBuilder! style, MarkupString.Display.DisplayOptions! options) -> void
+MarkupString.Display.Interaction
+MarkupString.Display.Interaction.<Clone>$() -> MarkupString.Display.Interaction!
+MarkupString.Display.Interaction.Choices.get -> System.Collections.Generic.IReadOnlyList<MarkupString.CommandChoice!>?
+MarkupString.Display.Interaction.Choices.init -> void
+MarkupString.Display.Interaction.Deconstruct(out MarkupString.Display.InteractionKind Kind, out string! Target) -> void
+MarkupString.Display.Interaction.Equals(MarkupString.Display.Interaction? other) -> bool
+MarkupString.Display.Interaction.Group.get -> string?
+MarkupString.Display.Interaction.Group.init -> void
+MarkupString.Display.Interaction.Hint.get -> string?
+MarkupString.Display.Interaction.Hint.init -> void
+MarkupString.Display.Interaction.Interaction(MarkupString.Display.InteractionKind Kind, string! Target) -> void
+MarkupString.Display.Interaction.Kind.get -> MarkupString.Display.InteractionKind
+MarkupString.Display.Interaction.Kind.init -> void
+MarkupString.Display.Interaction.Target.get -> string!
+MarkupString.Display.Interaction.Target.init -> void
+MarkupString.Display.InteractionKind
+MarkupString.Display.InteractionKind.Command = 1 -> MarkupString.Display.InteractionKind
+MarkupString.Display.InteractionKind.Prompt = 2 -> MarkupString.Display.InteractionKind
+MarkupString.Display.InteractionKind.Url = 0 -> MarkupString.Display.InteractionKind
+MarkupString.Display.SpanRenderer
+MarkupString.Display.StyleBuilder
+MarkupString.Display.StyleBuilder.Attributes.get -> MarkupString.Display.TextAttributes
+MarkupString.Display.StyleBuilder.Attributes.set -> void
+MarkupString.Display.StyleBuilder.Background.get -> MarkupString.RgbColor?
+MarkupString.Display.StyleBuilder.Background.set -> void
+MarkupString.Display.StyleBuilder.Foreground.get -> MarkupString.RgbColor?
+MarkupString.Display.StyleBuilder.Foreground.set -> void
+MarkupString.Display.StyleBuilder.Interaction.get -> MarkupString.Display.Interaction?
+MarkupString.Display.StyleBuilder.Interaction.set -> void
+MarkupString.Display.StyleBuilder.Pane.get -> string?
+MarkupString.Display.StyleBuilder.Pane.set -> void
+MarkupString.Display.StyleBuilder.Picture.get -> MarkupString.ImageMarkup?
+MarkupString.Display.StyleBuilder.Picture.set -> void
+MarkupString.Display.StyleBuilder.StyleBuilder() -> void
+MarkupString.Display.VocabularyStyles
+MarkupString.Display.VocabularyStyles.Contribute(MarkupString.MarkupSet! markups, MarkupString.Display.StyleBuilder! style, MarkupString.Display.DisplayOptions! options) -> void
+MarkupString.HighlightMarkup
+MarkupString.HighlightMarkup.<Clone>$() -> MarkupString.HighlightMarkup!
+MarkupString.HighlightMarkup.Color.get -> MarkupString.RgbColor
+MarkupString.HighlightMarkup.Color.init -> void
+MarkupString.HighlightMarkup.Deconstruct(out MarkupString.RgbColor Color) -> void
+MarkupString.HighlightMarkup.Equals(MarkupString.HighlightMarkup? other) -> bool
+MarkupString.HighlightMarkup.HighlightMarkup(MarkupString.RgbColor Color) -> void
+override MarkupString.CommandChoice.Equals(object? obj) -> bool
+override MarkupString.CommandChoice.GetHashCode() -> int
+override MarkupString.CommandChoice.ToString() -> string!
+override MarkupString.CommandMenuMarkup.Equals(object? obj) -> bool
+override MarkupString.CommandMenuMarkup.GetHashCode() -> int
+override MarkupString.CommandMenuMarkup.ToString() -> string!
+override MarkupString.Display.Cell.GetHashCode() -> int
+override MarkupString.Display.CellPoint.GetHashCode() -> int
+override MarkupString.Display.DisplayOptions.Equals(object? obj) -> bool
+override MarkupString.Display.DisplayOptions.GetHashCode() -> int
+override MarkupString.Display.DisplayOptions.ToString() -> string!
+override MarkupString.Display.DisplaySpan.GetHashCode() -> int
+override MarkupString.Display.DisplayStyle.GetHashCode() -> int
+override MarkupString.Display.Interaction.Equals(object? obj) -> bool
+override MarkupString.Display.Interaction.GetHashCode() -> int
+override MarkupString.Display.Interaction.ToString() -> string!
+override MarkupString.HighlightMarkup.Equals(object? obj) -> bool
+override MarkupString.HighlightMarkup.GetHashCode() -> int
+override MarkupString.HighlightMarkup.ToString() -> string!
+static MarkupString.CommandChoice.operator !=(MarkupString.CommandChoice? left, MarkupString.CommandChoice? right) -> bool
+static MarkupString.CommandChoice.operator ==(MarkupString.CommandChoice? left, MarkupString.CommandChoice? right) -> bool
+static MarkupString.CommandMenuMarkup.operator !=(MarkupString.CommandMenuMarkup? left, MarkupString.CommandMenuMarkup? right) -> bool
+static MarkupString.CommandMenuMarkup.operator ==(MarkupString.CommandMenuMarkup? left, MarkupString.CommandMenuMarkup? right) -> bool
+static MarkupString.Display.Cell.operator !=(MarkupString.Display.Cell left, MarkupString.Display.Cell right) -> bool
+static MarkupString.Display.Cell.operator ==(MarkupString.Display.Cell left, MarkupString.Display.Cell right) -> bool
+static MarkupString.Display.CellPoint.operator !=(MarkupString.Display.CellPoint left, MarkupString.Display.CellPoint right) -> bool
+static MarkupString.Display.CellPoint.operator ==(MarkupString.Display.CellPoint left, MarkupString.Display.CellPoint right) -> bool
+static MarkupString.Display.CellRenderer.Layout(MarkupString.MarkupText! text, int columns, MarkupString.Display.DisplayRegistry! registry, MarkupString.Display.DisplayOptions! options, bool wordWrap = false) -> MarkupString.Display.CellLayout!
+static MarkupString.Display.DisplayOptions.operator !=(MarkupString.Display.DisplayOptions? left, MarkupString.Display.DisplayOptions? right) -> bool
+static MarkupString.Display.DisplayOptions.operator ==(MarkupString.Display.DisplayOptions? left, MarkupString.Display.DisplayOptions? right) -> bool
+static MarkupString.Display.DisplayRegistry.Core.get -> MarkupString.Display.DisplayRegistry!
+static MarkupString.Display.DisplayRegistry.Empty.get -> MarkupString.Display.DisplayRegistry!
+static MarkupString.Display.DisplaySpan.operator !=(MarkupString.Display.DisplaySpan left, MarkupString.Display.DisplaySpan right) -> bool
+static MarkupString.Display.DisplaySpan.operator ==(MarkupString.Display.DisplaySpan left, MarkupString.Display.DisplaySpan right) -> bool
+static MarkupString.Display.DisplayStyle.Plain.get -> MarkupString.Display.DisplayStyle
+static MarkupString.Display.DisplayStyle.operator !=(MarkupString.Display.DisplayStyle left, MarkupString.Display.DisplayStyle right) -> bool
+static MarkupString.Display.DisplayStyle.operator ==(MarkupString.Display.DisplayStyle left, MarkupString.Display.DisplayStyle right) -> bool
+static MarkupString.Display.Interaction.operator !=(MarkupString.Display.Interaction? left, MarkupString.Display.Interaction? right) -> bool
+static MarkupString.Display.Interaction.operator ==(MarkupString.Display.Interaction? left, MarkupString.Display.Interaction? right) -> bool
+static MarkupString.Display.SpanRenderer.Css(MarkupString.Display.DisplayStyle style) -> string!
+static MarkupString.Display.SpanRenderer.CssClasses(MarkupString.Display.DisplayStyle style) -> string!
+static MarkupString.Display.SpanRenderer.Hex(MarkupString.RgbColor color) -> string!
+static MarkupString.Display.SpanRenderer.Render(MarkupString.MarkupText! text, MarkupString.Display.DisplayRegistry! registry, MarkupString.Display.DisplayOptions! options) -> System.Collections.Generic.IReadOnlyList<MarkupString.Display.DisplaySpan>!
+static MarkupString.Display.VocabularyStyles.Instance.get -> MarkupString.Display.VocabularyStyles!
+static MarkupString.HighlightMarkup.operator !=(MarkupString.HighlightMarkup? left, MarkupString.HighlightMarkup? right) -> bool
+static MarkupString.HighlightMarkup.operator ==(MarkupString.HighlightMarkup? left, MarkupString.HighlightMarkup? right) -> bool
+~override MarkupString.Display.Cell.Equals(object obj) -> bool
+~override MarkupString.Display.Cell.ToString() -> string
+~override MarkupString.Display.CellPoint.Equals(object obj) -> bool
+~override MarkupString.Display.CellPoint.ToString() -> string
+~override MarkupString.Display.DisplaySpan.Equals(object obj) -> bool
+~override MarkupString.Display.DisplaySpan.ToString() -> string
+~override MarkupString.Display.DisplayStyle.Equals(object obj) -> bool
+~override MarkupString.Display.DisplayStyle.ToString() -> string

From ad9472885484652f4d082bc4c26bfb310c6d19fb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 21:45:09 +0000
Subject: [PATCH 05/19] Add terminal decoding plugins, conceal, and terminal
 styles for display

---
 MarkupString.Ansi/AnsiCss.cs                  |   1 +
 MarkupString.Ansi/AnsiMarkupCodec.cs          |   2 +
 MarkupString.Ansi/AnsiStyle.cs                |   7 +-
 MarkupString.Ansi/Decoding/AnsiDisplay.cs     | 184 ++++++
 MarkupString.Ansi/Decoding/VtPlugins.cs       | 620 ++++++++++++++++++
 .../Emitters/AnsiEmitterSupport.cs            |   2 +-
 MarkupString.Ansi/Emitters/AnsiHtmlEmitter.cs |   3 +-
 MarkupString.Ansi/PublicAPI.Unshipped.txt     |  49 ++
 MarkupString.Ansi/SgrWriter.cs                |   2 +
 9 files changed, 867 insertions(+), 3 deletions(-)
 create mode 100644 MarkupString.Ansi/Decoding/AnsiDisplay.cs
 create mode 100644 MarkupString.Ansi/Decoding/VtPlugins.cs

diff --git a/MarkupString.Ansi/AnsiCss.cs b/MarkupString.Ansi/AnsiCss.cs
index e9ffd86..fb74c57 100644
--- a/MarkupString.Ansi/AnsiCss.cs
+++ b/MarkupString.Ansi/AnsiCss.cs
@@ -33,6 +33,7 @@ public static class AnsiCss
 		".ms-underline { text-decoration: underline; }\n" +
 		".ms-strike { text-decoration: line-through; }\n" +
 		".ms-overline { text-decoration: overline; }\n" +
+		".ms-conceal { color: transparent; }\n" +
 		".ms-blink { animation: ms-blink 1s step-start infinite; }\n" +
 		".ms-invert { color: var(--ms-bg, #000); background-color: var(--ms-fg, #fff); }\n" +
 		".ms-cmd-link { cursor: pointer; text-decoration: underline dotted; }\n" +
diff --git a/MarkupString.Ansi/AnsiMarkupCodec.cs b/MarkupString.Ansi/AnsiMarkupCodec.cs
index ad5a57d..5ebb598 100644
--- a/MarkupString.Ansi/AnsiMarkupCodec.cs
+++ b/MarkupString.Ansi/AnsiMarkupCodec.cs
@@ -52,6 +52,7 @@ public void Write(Utf8JsonWriter writer, IMarkup markup)
 		if (style.Overlined) writer.WriteNumber("ov", 1);
 		if (style.Underlined) writer.WriteNumber("un", 1);
 		if (style.StrikeThrough) writer.WriteNumber("st", 1);
+		if (style.Concealed) writer.WriteNumber("cn", 1);
 		if (style.BlinkOff) writer.WriteNumber("nbl", 1);
 		if (style.BoldOff) writer.WriteNumber("nbo", 1);
 		if (style.InvertedOff) writer.WriteNumber("nin", 1);
@@ -80,6 +81,7 @@ public IMarkup Read(JsonElement element) =>
 			Overlined = element.TryGetProperty("ov", out _),
 			Underlined = element.TryGetProperty("un", out _),
 			StrikeThrough = element.TryGetProperty("st", out _),
+			Concealed = element.TryGetProperty("cn", out _),
 			BlinkOff = element.TryGetProperty("nbl", out _),
 			BoldOff = element.TryGetProperty("nbo", out _),
 			InvertedOff = element.TryGetProperty("nin", out _),
diff --git a/MarkupString.Ansi/AnsiStyle.cs b/MarkupString.Ansi/AnsiStyle.cs
index 39967d7..61b23ca 100644
--- a/MarkupString.Ansi/AnsiStyle.cs
+++ b/MarkupString.Ansi/AnsiStyle.cs
@@ -30,6 +30,9 @@ public readonly record struct AnsiStyle
 	public bool Inverted { get; init; }
 	public bool StrikeThrough { get; init; }
 
+	/// <summary>Hidden (SGR 8): drawn in the background colour, as a password is, but still text to copy.</summary>
+	public bool Concealed { get; init; }
+
 	/// <summary>
 	/// Set by the <c>F</c> code: blink is off in this span, whatever encloses it. See <see cref="Combine"/>.
 	/// </summary>
@@ -87,6 +90,7 @@ public readonly record struct AnsiStyle
 		| (InvertedOff ? 1 << 10 : 0)
 		| (UnderlinedOff ? 1 << 11 : 0)
 		| (Clear ? 1 << 12 : 0)
+		| (Concealed ? 1 << 13 : 0)
 		| ((int)LinkKind << 16);
 
 	/// <summary>Field-by-field equality, written out because a style is compared each time a markup set is looked up.</summary>
@@ -108,7 +112,7 @@ public override int GetHashCode() =>
 	/// </summary>
 	public bool HasAnyAttribute =>
 		Foreground is not null || Background is not null ||
-		Bold || Faint || Italic || Underlined || Overlined || Blink || Inverted || StrikeThrough || Clear ||
+		Bold || Faint || Italic || Underlined || Overlined || Blink || Inverted || StrikeThrough || Concealed || Clear ||
 		BlinkOff || BoldOff || InvertedOff || UnderlinedOff;
 
 	/// <summary>
@@ -156,6 +160,7 @@ public AnsiStyle Combine(AnsiStyle inner)
 			Blink = (outer.Blink || inner.Blink) && !inner.BlinkOff,
 			Inverted = (outer.Inverted || inner.Inverted) && !inner.InvertedOff,
 			StrikeThrough = outer.StrikeThrough || inner.StrikeThrough,
+			Concealed = outer.Concealed || inner.Concealed,
 			// Still off for whatever this span encloses, unless it turns the attribute back on.
 			BlinkOff = inner.BlinkOff || (outer.BlinkOff && !inner.Blink),
 			BoldOff = inner.BoldOff || (outer.BoldOff && !inner.Bold),
diff --git a/MarkupString.Ansi/Decoding/AnsiDisplay.cs b/MarkupString.Ansi/Decoding/AnsiDisplay.cs
new file mode 100644
index 0000000..9c73f16
--- /dev/null
+++ b/MarkupString.Ansi/Decoding/AnsiDisplay.cs
@@ -0,0 +1,184 @@
+using MarkupString.Display;
+namespace MarkupString.Ansi.Decoding;
+
+/// <summary>Registers terminal styles on a <see cref="DisplayRegistry"/>, and reads a terminal's capabilities.</summary>
+public static class AnsiDisplay
+{
+	/// <summary>The registry with <see cref="AnsiStyles"/> added.</summary>
+	/// <param name="registry">The registry.</param>
+	/// <param name="boldIsBright">Draw bold text in a standard colour in its bright version, as many MUD clients do.</param>
+	public static DisplayRegistry WithAnsi(this DisplayRegistry registry, bool boldIsBright = false)
+	{
+		ArgumentNullException.ThrowIfNull(registry);
+		return registry.With(boldIsBright ? AnsiStyles.BoldIsBright : AnsiStyles.Instance);
+	}
+
+	/// <summary>The shared vocabulary and terminal styles.</summary>
+	public static DisplayRegistry Default { get; } = DisplayRegistry.Core.WithAnsi();
+
+	/// <summary>What a terminal shows, from its profile and the colour depth the host settled on.</summary>
+	public static OutputCapabilities ToOutputCapabilities(this TerminalProfile profile, AnsiColorDepth depth)
+	{
+		ArgumentNullException.ThrowIfNull(profile);
+		var features = profile.Features;
+		var pictures = PictureMethods.None;
+		if ((features & TerminalFeatures.KittyGraphics) != 0) pictures |= PictureMethods.KittyPlaceholders;
+		if ((features & TerminalFeatures.InlineImages) != 0) pictures |= PictureMethods.InlineImages;
+		if ((features & TerminalFeatures.Sixel) != 0) pictures |= PictureMethods.Sixel;
+		if ((features & TerminalFeatures.BlockArt) != 0) pictures |= PictureMethods.HalfBlocks;
+
+		var interactions = InteractionKinds.None;
+		if ((features & TerminalFeatures.Hyperlinks) != 0) interactions |= InteractionKinds.Url;
+		if ((features & TerminalFeatures.CommandLinks) != 0) interactions |= InteractionKinds.Command;
+
+		return new OutputCapabilities
+		{
+			Colors = depth switch
+			{
+				AnsiColorDepth.TrueColor => ColorLevel.TrueColor,
+				AnsiColorDepth.Xterm256 => ColorLevel.Xterm256,
+				AnsiColorDepth.Standard => ColorLevel.Standard,
+				AnsiColorDepth.Attributes => ColorLevel.Attributes,
+				_ => ColorLevel.None,
+			},
+			Attributes = TextAttributes.All,
+			Interactions = interactions,
+			Pictures = pictures,
+			MovingPictures = (features & TerminalFeatures.MovingPictures) != 0,
+		};
+	}
+
+	/// <summary>The colour depth an output shows, for an ANSI writer.</summary>
+	public static AnsiColorDepth ToColorDepth(this OutputCapabilities capabilities)
+	{
+		ArgumentNullException.ThrowIfNull(capabilities);
+		return capabilities.Colors switch
+		{
+			ColorLevel.TrueColor => AnsiColorDepth.TrueColor,
+			ColorLevel.Xterm256 => AnsiColorDepth.Xterm256,
+			ColorLevel.Standard => AnsiColorDepth.Standard,
+			ColorLevel.Attributes => AnsiColorDepth.Attributes,
+			_ => AnsiColorDepth.None,
+		};
+	}
+
+	/// <summary>The terminal features an output has, for an ANSI writer.</summary>
+	public static TerminalFeatures ToTerminalFeatures(this OutputCapabilities capabilities)
+	{
+		ArgumentNullException.ThrowIfNull(capabilities);
+		var features = TerminalFeatures.None;
+		if ((capabilities.Interactions & InteractionKinds.Url) != 0) features |= TerminalFeatures.Hyperlinks;
+		if ((capabilities.Interactions & InteractionKinds.Command) != 0) features |= TerminalFeatures.CommandLinks;
+		if ((capabilities.Pictures & PictureMethods.KittyPlaceholders) != 0) features |= TerminalFeatures.KittyGraphics;
+		if ((capabilities.Pictures & PictureMethods.InlineImages) != 0) features |= TerminalFeatures.InlineImages;
+		if ((capabilities.Pictures & PictureMethods.Sixel) != 0) features |= TerminalFeatures.Sixel;
+		if ((capabilities.Pictures & PictureMethods.HalfBlocks) != 0) features |= TerminalFeatures.BlockArt;
+		if (capabilities.MovingPictures) features |= TerminalFeatures.MovingPictures;
+		return features;
+	}
+}
+
+/// <summary>
+/// Folds every layer with a terminal style (<see cref="IAnsiStyleSource"/>: SGR, an MXP colour, an HTML
+/// <c>&lt;b&gt;</c>) into colours, attributes and a link, outermost first as <see cref="AnsiStyle.Combine"/> nests them.
+/// </summary>
+public sealed class AnsiStyles : IStyleContributor
+{
+	private readonly bool _boldIsBright;
+
+	private AnsiStyles(bool boldIsBright) => _boldIsBright = boldIsBright;
+
+	/// <summary>Colours as they are written.</summary>
+	public static AnsiStyles Instance { get; } = new(false);
+
+	/// <summary>Bold text in a standard colour drawn in its bright version.</summary>
+	public static AnsiStyles BoldIsBright { get; } = new(true);
+
+	/// <inheritdoc/>
+	public void Contribute(MarkupSet markups, StyleBuilder style, DisplayOptions options)
+	{
+		ArgumentNullException.ThrowIfNull(markups);
+		ArgumentNullException.ThrowIfNull(style);
+		ArgumentNullException.ThrowIfNull(options);
+
+		var folded = AnsiStyle.None;
+		var any = false;
+		for (var i = markups.Count - 1; i >= 0; i--)
+		{
+			if (markups[i] is IAnsiStyleSource source && source.TryGetAnsiStyle(MarkupFormat.Ansi, out var layer))
+			{
+				folded = folded.Combine(layer);
+				any = true;
+			}
+		}
+
+		if (!any) return;
+
+		var colors = options.Colors ?? AnsiColors.Default;
+		var foreground = folded.Foreground;
+		if (_boldIsBright && folded.Bold && foreground is AnsiColor.Standard { Bright: false } standard)
+		{
+			foreground = AnsiColor.StandardOf(standard.Index, true);
+		}
+
+		if (Resolve(foreground, colors) is { } fg) style.Foreground = fg;
+		if (Resolve(folded.Background, colors) is { } bg) style.Background ??= bg;
+
+		var attributes = TextAttributes.None;
+		if (folded.Bold) attributes |= TextAttributes.Bold;
+		if (folded.Faint) attributes |= TextAttributes.Faint;
+		if (folded.Italic) attributes |= TextAttributes.Italic;
+		if (folded.Underlined) attributes |= TextAttributes.Underline;
+		if (folded.Blink) attributes |= TextAttributes.Blink;
+		if (folded.Inverted) attributes |= TextAttributes.Inverse;
+		if (folded.Concealed) attributes |= TextAttributes.Conceal;
+		if (folded.StrikeThrough) attributes |= TextAttributes.Strikethrough;
+		if (folded.Overlined) attributes |= TextAttributes.Overline;
+		style.Attributes |= attributes;
+
+		if (!string.IsNullOrEmpty(folded.LinkUrl) && style.Interaction is null)
+		{
+			if (folded.LinkKind == LinkKind.Command)
+			{
+				style.Interaction = new Interaction(InteractionKind.Command, folded.LinkUrl) { Hint = folded.LinkText };
+			}
+			else if (UrlSafety.IsSafeNavigableUrl(folded.LinkUrl))
+			{
+				style.Interaction = new Interaction(InteractionKind.Url, folded.LinkUrl) { Hint = folded.LinkText };
+			}
+		}
+	}
+
+	private static RgbColor? Resolve(AnsiColor? color, IColorResolver colors) => color switch
+	{
+		AnsiColor.Standard standard => colors.Standard(standard.Index, standard.Bright),
+		AnsiColor.Xterm { Index: < 16 } xterm => colors.Standard(xterm.Index & 7, xterm.Index >= 8),
+		AnsiColor.Xterm xterm => colors.Xterm(xterm.Index),
+		AnsiColor.Rgb rgb => new RgbColor(rgb.R, rgb.G, rgb.B),
+		_ => null,
+	};
+}
+
+/// <summary>The xterm palette, as <see cref="AnsiPalette"/> has it, as an <see cref="IColorResolver"/>.</summary>
+public class AnsiColors : IColorResolver
+{
+	/// <summary>The xterm palette, text left as it is.</summary>
+	public static AnsiColors Default { get; } = new();
+
+	/// <inheritdoc/>
+	public virtual RgbColor Standard(int index, bool bright)
+	{
+		var rgb = AnsiPalette.Standard((byte)(index & 7), bright);
+		return new RgbColor(rgb.R, rgb.G, rgb.B);
+	}
+
+	/// <inheritdoc/>
+	public virtual RgbColor Xterm(int index)
+	{
+		var rgb = AnsiPalette.Xterm((byte)index);
+		return new RgbColor(rgb.R, rgb.G, rgb.B);
+	}
+
+	/// <inheritdoc/>
+	public virtual RgbColor Legible(RgbColor foreground, RgbColor background) => foreground;
+}
diff --git a/MarkupString.Ansi/Decoding/VtPlugins.cs b/MarkupString.Ansi/Decoding/VtPlugins.cs
new file mode 100644
index 0000000..4766333
--- /dev/null
+++ b/MarkupString.Ansi/Decoding/VtPlugins.cs
@@ -0,0 +1,620 @@
+using System.Globalization;
+using System.Text;
+using MarkupString.Decoding;
+using MarkupString.Display;
+namespace MarkupString.Ansi.Decoding;
+
+/// <summary>Registers the terminal plugins on a <see cref="DecoderRegistry"/>.</summary>
+public static class VtDecoding
+{
+	/// <summary>
+	/// The registry with SGR, the C0 controls and line editing, character sets, OSC (links, titles, palette,
+	/// clipboard) and the answers to terminal queries.
+	/// </summary>
+	public static DecoderRegistry WithVt(this DecoderRegistry registry)
+	{
+		ArgumentNullException.ThrowIfNull(registry);
+		return registry
+			.With(SgrPlugin.Instance)
+			.With(ControlsPlugin.Instance)
+			.With(CharsetPlugin.Instance)
+			.With(OscPlugin.Instance)
+			.With(AnswersPlugin.Instance);
+	}
+
+	/// <summary>A registry with nothing but the terminal plugins.</summary>
+	public static DecoderRegistry Terminal { get; } = DecoderRegistry.Empty.WithVt();
+}
+
+/// <summary>The pen slots the terminal plugins write under, for a plugin that wants to read or replace them.</summary>
+public static class VtPens
+{
+	/// <summary>The SGR style, an <see cref="AnsiMarkup"/>.</summary>
+	public const string Style = "sgr";
+
+	/// <summary>The OSC 8 or MSLP link, an <see cref="AnsiMarkup"/> with only a link.</summary>
+	public const string Link = "link";
+}
+
+/// <summary>SGR (<c>CSI … m</c>): colours and attributes, colon subparameters included.</summary>
+public sealed class SgrPlugin : IDecoderPlugin
+{
+	/// <summary>The one instance.</summary>
+	public static SgrPlugin Instance { get; } = new();
+
+	private SgrPlugin()
+	{
+	}
+
+	/// <inheritdoc/>
+	public string Name => "sgr";
+
+	/// <inheritdoc/>
+	public void Register(DecoderBuilder builder)
+	{
+		ArgumentNullException.ThrowIfNull(builder);
+		builder.OnCsi('m', static (in CsiSequence sequence, DecodeContext context) =>
+		{
+			var state = context.State<VtState>();
+			var before = state.Style;
+			state.Style = Apply(state.Style, sequence);
+			if (before.Underlined && !state.Style.Underlined && state.MslpUnderlined)
+			{
+				// The underline is an MSLP link's extent.
+				context.SetPen(VtPens.Link, null);
+				state.MslpUnderlined = false;
+			}
+			else if (!before.Underlined && state.Style.Underlined && context.Pen(VtPens.Link) is AnsiMarkup { Style.LinkKind: LinkKind.Command })
+			{
+				state.MslpUnderlined = true;
+			}
+
+			context.SetPen(VtPens.Style, state.Style.IsNone ? null : new AnsiMarkup(state.Style));
+			return true;
+		});
+	}
+
+	/// <summary><paramref name="style"/> with the parameters of an SGR sequence applied.</summary>
+	public static AnsiStyle Apply(AnsiStyle style, in CsiSequence sequence)
+	{
+		if (sequence.Count == 0) return AnsiStyle.None;
+
+		for (var i = 0; i < sequence.Count; i++)
+		{
+			var code = sequence.Get(i);
+			var colon = i + 1 < sequence.Count && sequence.IsSubparameter(i + 1);
+			switch (code)
+			{
+				case 0: style = AnsiStyle.None; break;
+				case 1: style = style with { Bold = true }; break;
+				case 2: style = style with { Faint = true }; break;
+				case 3: style = style with { Italic = true }; break;
+				case 4:
+					// 4:0 is no underline; 4:1 to 4:5 are kinds of underline, all drawn as one.
+					style = style with { Underlined = !colon || sequence.Get(i + 1) != 0 };
+					break;
+				case 5 or 6: style = style with { Blink = true }; break;
+				case 7: style = style with { Inverted = true }; break;
+				case 8: style = style with { Concealed = true }; break;
+				case 9: style = style with { StrikeThrough = true }; break;
+				case 21: style = style with { Underlined = true }; break;
+				case 22: style = style with { Bold = false, Faint = false }; break;
+				case 23: style = style with { Italic = false }; break;
+				case 24: style = style with { Underlined = false }; break;
+				case 25: style = style with { Blink = false }; break;
+				case 27: style = style with { Inverted = false }; break;
+				case 28: style = style with { Concealed = false }; break;
+				case 29: style = style with { StrikeThrough = false }; break;
+				case >= 30 and <= 37: style = style with { Foreground = AnsiColor.StandardOf((byte)(code - 30), false) }; break;
+				case 38: style = style with { Foreground = Extended(sequence, ref i) ?? style.Foreground }; break;
+				case 39: style = style with { Foreground = null }; break;
+				case >= 40 and <= 47: style = style with { Background = AnsiColor.StandardOf((byte)(code - 40), false) }; break;
+				case 48: style = style with { Background = Extended(sequence, ref i) ?? style.Background }; break;
+				case 49: style = style with { Background = null }; break;
+				case 53: style = style with { Overlined = true }; break;
+				case 55: style = style with { Overlined = false }; break;
+				case 58: Extended(sequence, ref i); break;
+				case >= 90 and <= 97: style = style with { Foreground = AnsiColor.StandardOf((byte)(code - 90), true) }; break;
+				case >= 100 and <= 107: style = style with { Background = AnsiColor.StandardOf((byte)(code - 100), true) }; break;
+			}
+
+			// Subparameters belong to the code before them; whatever this code did not read is skipped.
+			while (i + 1 < sequence.Count && sequence.IsSubparameter(i + 1)) i++;
+		}
+
+		return style;
+	}
+
+	/// <summary>Reads <c>38;5;n</c>, <c>38;2;r;g;b</c> or their colon forms, leaving <paramref name="i"/> on the last parameter read.</summary>
+	private static AnsiColor? Extended(in CsiSequence sequence, ref int i)
+	{
+		if (i + 1 >= sequence.Count) return null;
+		var colon = sequence.IsSubparameter(i + 1);
+		var kind = sequence.Get(i + 1);
+		if (kind == 5)
+		{
+			if (i + 2 >= sequence.Count) return null;
+			var index = sequence.Get(i + 2);
+			i += 2;
+			return index is >= 0 and <= 255 ? AnsiColor.XtermOf((byte)index) : null;
+		}
+
+		if (kind != 2) return null;
+
+		var first = i + 2;
+		if (colon)
+		{
+			// 38:2:<colour space>:r:g:b, or 38:2:r:g:b from writers that leave the colour space out.
+			var count = 0;
+			while (first + count < sequence.Count && sequence.IsSubparameter(first + count)) count++;
+			if (count >= 4) first++;
+			else if (count < 3) return null;
+		}
+		else if (first + 2 >= sequence.Count)
+		{
+			return null;
+		}
+
+		var r = sequence.Get(first);
+		var g = sequence.Get(first + 1);
+		var b = sequence.Get(first + 2);
+		i = first + 2;
+		return r is >= 0 and <= 255 && g is >= 0 and <= 255 && b is >= 0 and <= 255
+			? new AnsiColor.Rgb((byte)r, (byte)g, (byte)b)
+			: null;
+	}
+}
+
+/// <summary>
+/// The C0 controls and line editing: bell, carriage return, backspace, tab, form feed, and <c>CSI K</c>,
+/// <c>CSI J</c>, <c>CSI G</c>, <c>CSI C</c> and <c>CSI D</c>.
+/// </summary>
+public sealed class ControlsPlugin : IDecoderPlugin
+{
+	/// <summary>Columns between tab stops.</summary>
+	public const int TabStop = 8;
+
+	/// <summary>The one instance.</summary>
+	public static ControlsPlugin Instance { get; } = new();
+
+	private ControlsPlugin()
+	{
+	}
+
+	/// <inheritdoc/>
+	public string Name => "controls";
+
+	/// <inheritdoc/>
+	public void Register(DecoderBuilder builder)
+	{
+		ArgumentNullException.ThrowIfNull(builder);
+		builder
+			.OnControl('\a', static (_, context) =>
+			{
+				context.Point(BellMarkup.Instance);
+				return true;
+			})
+			.OnControl('\r', static (_, context) =>
+			{
+				context.CarriageReturn();
+				return true;
+			})
+			.OnControl('\b', static (_, context) =>
+			{
+				context.Backspace();
+				return true;
+			})
+			.OnControl('\t', static (_, context) =>
+			{
+				context.MoveToColumn((context.Column / TabStop + 1) * TabStop);
+				return true;
+			})
+			.OnControl('\f', static (_, context) =>
+			{
+				context.Point(ClearScreenMarkup.Instance);
+				return true;
+			})
+			.OnControl('\v', static (_, context) =>
+			{
+				context.EndLine();
+				return true;
+			})
+			.OnCsi('K', static (in CsiSequence sequence, DecodeContext context) =>
+			{
+				switch (sequence.Get(0))
+				{
+					case 0: context.EraseToEndOfLine(); break;
+					case 1: context.EraseToStartOfLine(); break;
+					case 2: context.EraseLine(); break;
+					default: return false;
+				}
+
+				return true;
+			})
+			.OnCsi('J', static (in CsiSequence sequence, DecodeContext context) =>
+			{
+				// A scrolling pane has no screen below the cursor to erase; only a whole clear means anything.
+				if (sequence.Get(0) is 2 or 3) context.Point(ClearScreenMarkup.Instance);
+				return true;
+			})
+			.OnCsi('G', static (in CsiSequence sequence, DecodeContext context) =>
+			{
+				context.MoveToColumn(sequence.Get(0, 1) - 1);
+				return true;
+			})
+			.OnCsi('`', static (in CsiSequence sequence, DecodeContext context) =>
+			{
+				context.MoveToColumn(sequence.Get(0, 1) - 1);
+				return true;
+			})
+			.OnCsi('C', static (in CsiSequence sequence, DecodeContext context) =>
+			{
+				context.MoveToColumn(context.Column + Math.Max(1, sequence.Get(0, 1)));
+				return true;
+			})
+			.OnCsi('D', static (in CsiSequence sequence, DecodeContext context) =>
+			{
+				context.Backspace(Math.Max(1, sequence.Get(0, 1)));
+				return true;
+			});
+	}
+}
+
+/// <summary>The DEC special graphics set (<c>ESC ( 0</c>), and shifting between G0 and G1 with SO and SI.</summary>
+public sealed class CharsetPlugin : IDecoderPlugin
+{
+	// 0x5F to 0x7E in the DEC special graphics set.
+	private const string Graphics = " ◆▒␉␌␍␊°±␤␋┘┐┌└┼⎺⎻─⎼⎽├┤┴┬│≤≥π≠£·";
+
+	/// <summary>The one instance.</summary>
+	public static CharsetPlugin Instance { get; } = new();
+
+	private CharsetPlugin()
+	{
+	}
+
+	/// <inheritdoc/>
+	public string Name => "charsets";
+
+	/// <inheritdoc/>
+	public void Register(DecoderBuilder builder)
+	{
+		ArgumentNullException.ThrowIfNull(builder);
+		builder
+			.OnEsc('0', static (in EscSequence sequence, DecodeContext context) => Designate(sequence, context, true), "(")
+			.OnEsc('B', static (in EscSequence sequence, DecodeContext context) => Designate(sequence, context, false), "(")
+			.OnEsc('0', static (in EscSequence sequence, DecodeContext context) => Designate(sequence, context, true), ")")
+			.OnEsc('B', static (in EscSequence sequence, DecodeContext context) => Designate(sequence, context, false), ")")
+			.OnControl('\u000e', static (_, context) =>
+			{
+				context.State<VtState>().ShiftedOut = true;
+				return true;
+			})
+			.OnControl('\u000f', static (_, context) =>
+			{
+				context.State<VtState>().ShiftedOut = false;
+				return true;
+			})
+			.OnPrint(static (text, context) =>
+			{
+				var state = context.State<VtState>();
+				if (!(state.ShiftedOut ? state.G1Graphics : state.G0Graphics)) return false;
+
+				Span<char> mapped = text.Length <= 256 ? stackalloc char[text.Length] : new char[text.Length];
+				for (var i = 0; i < text.Length; i++)
+				{
+					var c = text[i];
+					mapped[i] = c is >= '_' and <= '~' ? Graphics[c - 0x5f] : c;
+				}
+
+				context.Write(mapped);
+				return true;
+			});
+	}
+
+	private static bool Designate(in EscSequence sequence, DecodeContext context, bool graphics)
+	{
+		var state = context.State<VtState>();
+		if (sequence.Intermediates[0] == '(') state.G0Graphics = graphics;
+		else state.G1Graphics = graphics;
+		return true;
+	}
+}
+
+/// <summary>
+/// Operating system commands: OSC 8 links, MSLP command links (OSC 68), titles (0, 1, 2), palette changes (4, 10,
+/// 11, 12, 104, 110, 111, 112) and the clipboard (52).
+/// </summary>
+public sealed class OscPlugin : IDecoderPlugin
+{
+	/// <summary>The longest OSC 8 address taken, as kitty and VTE cap it.</summary>
+	public const int MaxUriLength = 2083;
+
+	/// <summary>The one instance.</summary>
+	public static OscPlugin Instance { get; } = new();
+
+	private OscPlugin()
+	{
+	}
+
+	/// <inheritdoc/>
+	public string Name => "osc";
+
+	/// <inheritdoc/>
+	public void Register(DecoderBuilder builder)
+	{
+		ArgumentNullException.ThrowIfNull(builder);
+		builder
+			.OnOsc(8, static (payload, context) =>
+			{
+				// 8 ; params ; uri — an empty uri ends the link.
+				var separator = payload.IndexOf(';');
+				if (separator < 0) return false;
+				var uri = payload[(separator + 1)..];
+				if (uri.IsEmpty || uri.Length > MaxUriLength)
+				{
+					context.SetPen(VtPens.Link, null);
+					return true;
+				}
+
+				var target = uri.ToString();
+				context.SetPen(VtPens.Link, UrlSafety.IsSafeNavigableUrl(target)
+					? new AnsiMarkup(new AnsiStyle { LinkUrl = target, LinkKind = LinkKind.Url })
+					: null);
+				return true;
+			})
+			.OnOsc(68, static (payload, context) =>
+			{
+				// 68 ; 1 ; SEND ; command, before the underlined text that is the link.
+				var parts = payload.ToString().Split(';', 3);
+				if (parts is not ["1", var type, var command] || command.Length == 0) return false;
+				if (!type.Equals("SEND", StringComparison.OrdinalIgnoreCase)) return false;
+				context.SetPen(VtPens.Link, new AnsiMarkup(new AnsiStyle { LinkUrl = command, LinkKind = LinkKind.Command }));
+				context.State<VtState>().MslpUnderlined = false;
+				return true;
+			})
+			.OnOsc(0, static (payload, context) => Title(payload, context, icon: true))
+			.OnOsc(1, static (payload, context) => Title(payload, context, icon: true))
+			.OnOsc(2, static (payload, context) => Title(payload, context, icon: false))
+			.OnOsc(4, static (payload, context) =>
+			{
+				var parts = payload.ToString().Split(';');
+				for (var i = 0; i + 1 < parts.Length; i += 2)
+				{
+					if (!int.TryParse(parts[i], NumberStyles.None, CultureInfo.InvariantCulture, out var index) || index > 255) continue;
+					if (ParseColor(parts[i + 1]) is { } color) context.Raise(new PaletteEvent(PaletteSlot.Index, index, color));
+				}
+
+				return true;
+			})
+			.OnOsc(104, static (payload, context) =>
+			{
+				if (payload.IsEmpty)
+				{
+					context.Raise(new PaletteEvent(PaletteSlot.Index, -1, null));
+					return true;
+				}
+
+				foreach (var part in payload.ToString().Split(';'))
+				{
+					if (int.TryParse(part, NumberStyles.None, CultureInfo.InvariantCulture, out var index) && index <= 255)
+					{
+						context.Raise(new PaletteEvent(PaletteSlot.Index, index, null));
+					}
+				}
+
+				return true;
+			})
+			.OnOsc(10, static (payload, context) => Dynamic(payload, context, 10))
+			.OnOsc(11, static (payload, context) => Dynamic(payload, context, 11))
+			.OnOsc(12, static (payload, context) => Dynamic(payload, context, 12))
+			.OnOsc(110, static (_, context) => Reset(context, PaletteSlot.Foreground))
+			.OnOsc(111, static (_, context) => Reset(context, PaletteSlot.Background))
+			.OnOsc(112, static (_, context) => Reset(context, PaletteSlot.Cursor))
+			.OnOsc(52, static (payload, context) =>
+			{
+				var separator = payload.IndexOf(';');
+				if (separator < 0) return false;
+				var selection = payload[..separator].ToString();
+				var data = payload[(separator + 1)..];
+				if (data is "?")
+				{
+					context.Raise(new ClipboardEvent(selection, null));
+					return true;
+				}
+
+				var bytes = new byte[data.Length / 4 * 3 + 3];
+				if (!Convert.TryFromBase64Chars(data, bytes, out var written)) return true;
+				context.Raise(new ClipboardEvent(selection, Encoding.UTF8.GetString(bytes, 0, written)));
+				return true;
+			});
+	}
+
+	/// <summary>
+	/// An X11 colour specification as OSC 4, 10 and 11 take it: <c>rgb:r/g/b</c> with one to four hex digits a
+	/// channel, or <c>#rgb</c>, <c>#rrggbb</c>, <c>#rrrgggbbb</c>, <c>#rrrrggggbbbb</c>. Null when it is none of those.
+	/// </summary>
+	public static RgbColor? ParseColor(ReadOnlySpan<char> spec)
+	{
+		if (spec.StartsWith("rgb:", StringComparison.OrdinalIgnoreCase))
+		{
+			var rest = spec[4..];
+			Span<Range> channels = stackalloc Range[4];
+			if (rest.Split(channels, '/') != 3) return null;
+			var r = Channel(rest[channels[0]]);
+			var g = Channel(rest[channels[1]]);
+			var b = Channel(rest[channels[2]]);
+			return r is { } rr && g is { } gg && b is { } bb ? new RgbColor(rr, gg, bb) : null;
+		}
+
+		if (spec.Length > 1 && spec[0] == '#' && (spec.Length - 1) % 3 == 0 && spec.Length <= 13)
+		{
+			var size = (spec.Length - 1) / 3;
+			var r = Channel(spec.Slice(1, size));
+			var g = Channel(spec.Slice(1 + size, size));
+			var b = Channel(spec.Slice(1 + size * 2, size));
+			return r is { } rr && g is { } gg && b is { } bb ? new RgbColor(rr, gg, bb) : null;
+		}
+
+		return null;
+	}
+
+	/// <summary><paramref name="color"/> as an X11 <c>rgb:rrrr/gggg/bbbb</c> specification, as xterm answers.</summary>
+	public static string FormatColor(RgbColor color) =>
+		string.Create(CultureInfo.InvariantCulture, $"rgb:{color.R:x2}{color.R:x2}/{color.G:x2}{color.G:x2}/{color.B:x2}{color.B:x2}");
+
+	private static byte? Channel(ReadOnlySpan<char> hex)
+	{
+		if (hex.Length is < 1 or > 4) return null;
+		if (!int.TryParse(hex, NumberStyles.AllowHexSpecifier, CultureInfo.InvariantCulture, out var value)) return null;
+		var max = (1 << (hex.Length * 4)) - 1;
+		return (byte)Math.Round(value * 255.0 / max);
+	}
+
+	private static bool Title(ReadOnlySpan<char> payload, DecodeContext context, bool icon)
+	{
+		var title = new StringBuilder(payload.Length);
+		foreach (var c in payload)
+		{
+			if (!char.IsControl(c)) title.Append(c);
+		}
+
+		context.Raise(new TitleEvent(title.ToString(), icon));
+		return true;
+	}
+
+	private static bool Dynamic(ReadOnlySpan<char> payload, DecodeContext context, int command)
+	{
+		// OSC 10 ; a ; b sets 10 to a and 11 to b, and so on.
+		var parts = payload.ToString().Split(';');
+		for (var i = 0; i < parts.Length; i++)
+		{
+			var slot = (command + i) switch
+			{
+				10 => PaletteSlot.Foreground,
+				11 => PaletteSlot.Background,
+				12 => PaletteSlot.Cursor,
+				_ => (PaletteSlot?)null,
+			};
+			if (slot is not { } which) break;
+
+			if (parts[i] == "?")
+			{
+				AnswersPlugin.AnswerColor(context, which);
+			}
+			else if (ParseColor(parts[i]) is { } color)
+			{
+				context.Raise(new PaletteEvent(which, 0, color));
+			}
+		}
+
+		return true;
+	}
+
+	private static bool Reset(DecodeContext context, PaletteSlot slot)
+	{
+		context.Raise(new PaletteEvent(slot, 0, null));
+		return true;
+	}
+}
+
+/// <summary>
+/// Answers what a server may ask a terminal, from the decoder's <see cref="ClientIdentity"/>: device attributes,
+/// XTVERSION, the pane's size, the cursor's position and the default colours. Each is answered only when
+/// <see cref="ClientIdentity.Answers"/> allows it.
+/// </summary>
+public sealed class AnswersPlugin : IDecoderPlugin
+{
+	/// <summary>The one instance.</summary>
+	public static AnswersPlugin Instance { get; } = new();
+
+	private AnswersPlugin()
+	{
+	}
+
+	/// <inheritdoc/>
+	public string Name => "answers";
+
+	/// <inheritdoc/>
+	public void Register(DecoderBuilder builder)
+	{
+		ArgumentNullException.ThrowIfNull(builder);
+		builder
+			.OnCsi('c', static (in CsiSequence sequence, DecodeContext context) =>
+			{
+				if (sequence.Get(0) != 0) return false;
+				if (!Allowed(context, ClientAnswers.Identity)) return true;
+				// A VT220 with colour, and sixel when the client draws it.
+				var sixel = (context.Identity.Output.Pictures & PictureMethods.Sixel) != 0;
+				context.Reply(sixel ? "\e[?62;4;22c" : "\e[?62;22c");
+				return true;
+			})
+			.OnCsi('q', static (in CsiSequence sequence, DecodeContext context) =>
+			{
+				if (sequence.Get(0) != 0) return false;
+				if (Allowed(context, ClientAnswers.Identity)) context.Reply($"\eP>|{context.Identity.Name} {context.Identity.Version}\e\\");
+				return true;
+			}, prefix: '>')
+			.OnCsi('t', static (in CsiSequence sequence, DecodeContext context) =>
+			{
+				var identity = context.Identity;
+				var reply = sequence.Get(0) switch
+				{
+					14 => Format($"\e[4;{identity.Rows * identity.CellHeight};{identity.Columns * identity.CellWidth}t"),
+					16 => Format($"\e[6;{identity.CellHeight};{identity.CellWidth}t"),
+					18 => Format($"\e[8;{identity.Rows};{identity.Columns}t"),
+					_ => null,
+				};
+				if (reply is null) return false;
+				if (Allowed(context, ClientAnswers.Size)) context.Reply(reply);
+				return true;
+			})
+			.OnCsi('n', static (in CsiSequence sequence, DecodeContext context) =>
+			{
+				switch (sequence.Get(0))
+				{
+					case 5:
+						if (Allowed(context, ClientAnswers.Identity)) context.Reply("\e[0n");
+						return true;
+					case 6:
+						// The row is always the last: a scrolling pane writes at its bottom.
+						if (Allowed(context, ClientAnswers.CursorPosition)) context.Reply(Format($"\e[{context.Identity.Rows};{context.Column + 1}R"));
+						return true;
+					default:
+						return false;
+				}
+			});
+	}
+
+	internal static void AnswerColor(DecodeContext context, PaletteSlot slot)
+	{
+		if (!Allowed(context, ClientAnswers.Colors)) return;
+		var color = slot switch
+		{
+			PaletteSlot.Foreground => context.Identity.Foreground,
+			PaletteSlot.Background => context.Identity.Background,
+			_ => null,
+		};
+		if (color is not { } known) return;
+		var number = slot == PaletteSlot.Foreground ? 10 : 11;
+		context.Reply(Format($"\e]{number};{OscPlugin.FormatColor(known)}\e\\"));
+	}
+
+	private static bool Allowed(DecodeContext context, ClientAnswers answer) => (context.Identity.Answers & answer) != 0;
+
+	private static string Format(FormattableString text) => text.ToString(CultureInfo.InvariantCulture);
+}
+
+/// <summary>The terminal plugins' state for one decoder.</summary>
+internal sealed class VtState
+{
+	public AnsiStyle Style { get; set; }
+
+	public bool MslpUnderlined { get; set; }
+
+	public bool G0Graphics { get; set; }
+
+	public bool G1Graphics { get; set; }
+
+	public bool ShiftedOut { get; set; }
+}
diff --git a/MarkupString.Ansi/Emitters/AnsiEmitterSupport.cs b/MarkupString.Ansi/Emitters/AnsiEmitterSupport.cs
index fa1354f..04aa324 100644
--- a/MarkupString.Ansi/Emitters/AnsiEmitterSupport.cs
+++ b/MarkupString.Ansi/Emitters/AnsiEmitterSupport.cs
@@ -278,7 +278,7 @@ internal static void EmitTagged(
 	internal static bool LeavesState(in AnsiStyle style) =>
 		style.Foreground is not null || style.Background is not null
 		|| style.Bold || style.Faint || style.Italic || style.Underlined
-		|| style.Overlined || style.Blink || style.Inverted || style.StrikeThrough;
+		|| style.Overlined || style.Blink || style.Inverted || style.StrikeThrough || style.Concealed;
 
 	private static void WriteTaggedLink(
 		in AnsiStyle style,
diff --git a/MarkupString.Ansi/Emitters/AnsiHtmlEmitter.cs b/MarkupString.Ansi/Emitters/AnsiHtmlEmitter.cs
index 0b63e2e..e932af9 100644
--- a/MarkupString.Ansi/Emitters/AnsiHtmlEmitter.cs
+++ b/MarkupString.Ansi/Emitters/AnsiHtmlEmitter.cs
@@ -114,7 +114,7 @@ private static void WriteColor(int slot, string hex, bool background, IBufferWri
 	/// </summary>
 	private static bool HasClasses(in AnsiStyle style, bool hasColourStyle) =>
 		style.Bold || style.Faint || style.Italic || style.Underlined
-		|| style.StrikeThrough || style.Overlined || style.Blink
+		|| style.StrikeThrough || style.Overlined || style.Blink || style.Concealed
 		|| (style.Inverted && !hasColourStyle);
 
 	private static void WriteClasses(in AnsiStyle style, bool hasColourStyle, IBufferWriter<char> output)
@@ -127,6 +127,7 @@ private static void WriteClasses(in AnsiStyle style, bool hasColourStyle, IBuffe
 		AppendClass(style.StrikeThrough, "ms-strike", ref first, output);
 		AppendClass(style.Overlined, "ms-overline", ref first, output);
 		AppendClass(style.Blink, "ms-blink", ref first, output);
+		AppendClass(style.Concealed, "ms-conceal", ref first, output);
 		AppendClass(style.Inverted && !hasColourStyle, "ms-invert", ref first, output);
 	}
 
diff --git a/MarkupString.Ansi/PublicAPI.Unshipped.txt b/MarkupString.Ansi/PublicAPI.Unshipped.txt
index 5e64f6b..4f7f5b2 100644
--- a/MarkupString.Ansi/PublicAPI.Unshipped.txt
+++ b/MarkupString.Ansi/PublicAPI.Unshipped.txt
@@ -3,3 +3,52 @@ MarkupString.Ansi.AnsiMarkdownEmitter
 MarkupString.Ansi.AnsiMarkdownEmitter.AnsiMarkdownEmitter() -> void
 MarkupString.Ansi.AnsiMarkdownEmitter.Format.get -> MarkupString.MarkupFormat!
 MarkupString.Ansi.AnsiMarkdownEmitter.TryEmit(MarkupString.MarkupSet! set, System.ReadOnlySpan<char> body, in MarkupString.EmitContext context, System.Buffers.IBufferWriter<char>! output) -> bool
+MarkupString.Ansi.AnsiStyle.Concealed.get -> bool
+MarkupString.Ansi.AnsiStyle.Concealed.init -> void
+MarkupString.Ansi.Decoding.AnsiColors
+MarkupString.Ansi.Decoding.AnsiColors.AnsiColors() -> void
+MarkupString.Ansi.Decoding.AnsiDisplay
+MarkupString.Ansi.Decoding.AnsiStyles
+MarkupString.Ansi.Decoding.AnsiStyles.Contribute(MarkupString.MarkupSet! markups, MarkupString.Display.StyleBuilder! style, MarkupString.Display.DisplayOptions! options) -> void
+MarkupString.Ansi.Decoding.AnswersPlugin
+MarkupString.Ansi.Decoding.AnswersPlugin.Name.get -> string!
+MarkupString.Ansi.Decoding.AnswersPlugin.Register(MarkupString.Decoding.DecoderBuilder! builder) -> void
+MarkupString.Ansi.Decoding.CharsetPlugin
+MarkupString.Ansi.Decoding.CharsetPlugin.Name.get -> string!
+MarkupString.Ansi.Decoding.CharsetPlugin.Register(MarkupString.Decoding.DecoderBuilder! builder) -> void
+MarkupString.Ansi.Decoding.ControlsPlugin
+MarkupString.Ansi.Decoding.ControlsPlugin.Name.get -> string!
+MarkupString.Ansi.Decoding.ControlsPlugin.Register(MarkupString.Decoding.DecoderBuilder! builder) -> void
+MarkupString.Ansi.Decoding.OscPlugin
+MarkupString.Ansi.Decoding.OscPlugin.Name.get -> string!
+MarkupString.Ansi.Decoding.OscPlugin.Register(MarkupString.Decoding.DecoderBuilder! builder) -> void
+MarkupString.Ansi.Decoding.SgrPlugin
+MarkupString.Ansi.Decoding.SgrPlugin.Name.get -> string!
+MarkupString.Ansi.Decoding.SgrPlugin.Register(MarkupString.Decoding.DecoderBuilder! builder) -> void
+MarkupString.Ansi.Decoding.VtDecoding
+MarkupString.Ansi.Decoding.VtPens
+const MarkupString.Ansi.Decoding.ControlsPlugin.TabStop = 8 -> int
+const MarkupString.Ansi.Decoding.OscPlugin.MaxUriLength = 2083 -> int
+const MarkupString.Ansi.Decoding.VtPens.Link = "link" -> string!
+const MarkupString.Ansi.Decoding.VtPens.Style = "sgr" -> string!
+static MarkupString.Ansi.Decoding.AnsiColors.Default.get -> MarkupString.Ansi.Decoding.AnsiColors!
+static MarkupString.Ansi.Decoding.AnsiDisplay.Default.get -> MarkupString.Display.DisplayRegistry!
+static MarkupString.Ansi.Decoding.AnsiDisplay.ToColorDepth(this MarkupString.Display.OutputCapabilities! capabilities) -> MarkupString.Ansi.AnsiColorDepth
+static MarkupString.Ansi.Decoding.AnsiDisplay.ToOutputCapabilities(this MarkupString.Ansi.TerminalProfile! profile, MarkupString.Ansi.AnsiColorDepth depth) -> MarkupString.Display.OutputCapabilities!
+static MarkupString.Ansi.Decoding.AnsiDisplay.ToTerminalFeatures(this MarkupString.Display.OutputCapabilities! capabilities) -> MarkupString.Ansi.TerminalFeatures
+static MarkupString.Ansi.Decoding.AnsiDisplay.WithAnsi(this MarkupString.Display.DisplayRegistry! registry, bool boldIsBright = false) -> MarkupString.Display.DisplayRegistry!
+static MarkupString.Ansi.Decoding.AnsiStyles.BoldIsBright.get -> MarkupString.Ansi.Decoding.AnsiStyles!
+static MarkupString.Ansi.Decoding.AnsiStyles.Instance.get -> MarkupString.Ansi.Decoding.AnsiStyles!
+static MarkupString.Ansi.Decoding.AnswersPlugin.Instance.get -> MarkupString.Ansi.Decoding.AnswersPlugin!
+static MarkupString.Ansi.Decoding.CharsetPlugin.Instance.get -> MarkupString.Ansi.Decoding.CharsetPlugin!
+static MarkupString.Ansi.Decoding.ControlsPlugin.Instance.get -> MarkupString.Ansi.Decoding.ControlsPlugin!
+static MarkupString.Ansi.Decoding.OscPlugin.FormatColor(MarkupString.RgbColor color) -> string!
+static MarkupString.Ansi.Decoding.OscPlugin.Instance.get -> MarkupString.Ansi.Decoding.OscPlugin!
+static MarkupString.Ansi.Decoding.OscPlugin.ParseColor(System.ReadOnlySpan<char> spec) -> MarkupString.RgbColor?
+static MarkupString.Ansi.Decoding.SgrPlugin.Apply(MarkupString.Ansi.AnsiStyle style, in MarkupString.Decoding.CsiSequence sequence) -> MarkupString.Ansi.AnsiStyle
+static MarkupString.Ansi.Decoding.SgrPlugin.Instance.get -> MarkupString.Ansi.Decoding.SgrPlugin!
+static MarkupString.Ansi.Decoding.VtDecoding.Terminal.get -> MarkupString.Decoding.DecoderRegistry!
+static MarkupString.Ansi.Decoding.VtDecoding.WithVt(this MarkupString.Decoding.DecoderRegistry! registry) -> MarkupString.Decoding.DecoderRegistry!
+virtual MarkupString.Ansi.Decoding.AnsiColors.Legible(MarkupString.RgbColor foreground, MarkupString.RgbColor background) -> MarkupString.RgbColor
+virtual MarkupString.Ansi.Decoding.AnsiColors.Standard(int index, bool bright) -> MarkupString.RgbColor
+virtual MarkupString.Ansi.Decoding.AnsiColors.Xterm(int index) -> MarkupString.RgbColor
diff --git a/MarkupString.Ansi/SgrWriter.cs b/MarkupString.Ansi/SgrWriter.cs
index 9d003b0..adb60ac 100644
--- a/MarkupString.Ansi/SgrWriter.cs
+++ b/MarkupString.Ansi/SgrWriter.cs
@@ -120,6 +120,7 @@ private static bool Removes(in AnsiStyle from, in AnsiStyle to) =>
 		|| (from.Blink && !to.Blink)
 		|| (from.Inverted && !to.Inverted)
 		|| (from.StrikeThrough && !to.StrikeThrough)
+		|| (from.Concealed && !to.Concealed)
 		|| (from.Foreground is not null && to.Foreground is null)
 		|| (from.Background is not null && to.Background is null);
 
@@ -150,6 +151,7 @@ private static bool WriteDifference(in AnsiStyle from, in AnsiStyle to, IBufferW
 		if (to.Blink && !from.Blink) codes.Add(5);
 		if (to.Inverted && !from.Inverted) codes.Add(7);
 		if (to.StrikeThrough && !from.StrikeThrough) codes.Add(9);
+		if (to.Concealed && !from.Concealed) codes.Add(8);
 
 		// A bright foreground's bold parameter is always covered by the attribute pass above, since
 		// IsBold(to) is true whenever it is set.

From 147e39ed84d318c4128c87a2aa8c87a2a5bf6129 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 21:48:06 +0000
Subject: [PATCH 06/19] Test the tokenizer, terminal plugins and renderers

---
 MarkupString.Tests/Decoding/DisplayTests.cs   | 191 +++++++++++
 .../Decoding/VtDecodingTests.cs               | 311 ++++++++++++++++++
 .../Decoding/VtTokenizerTests.cs              | 120 +++++++
 3 files changed, 622 insertions(+)
 create mode 100644 MarkupString.Tests/Decoding/DisplayTests.cs
 create mode 100644 MarkupString.Tests/Decoding/VtDecodingTests.cs
 create mode 100644 MarkupString.Tests/Decoding/VtTokenizerTests.cs

diff --git a/MarkupString.Tests/Decoding/DisplayTests.cs b/MarkupString.Tests/Decoding/DisplayTests.cs
new file mode 100644
index 0000000..13fbacc
--- /dev/null
+++ b/MarkupString.Tests/Decoding/DisplayTests.cs
@@ -0,0 +1,191 @@
+using MarkupString.Ansi;
+using MarkupString.Ansi.Decoding;
+using MarkupString.Display;
+
+public class DisplayTests
+{
+	private static readonly AnsiMarkup Red = AnsiMarkup.Create(foreground: new AnsiColor.Standard(1, false));
+	private static readonly AnsiMarkup Link = new(new AnsiStyle { LinkUrl = "look", LinkKind = LinkKind.Command });
+	private static readonly DisplayOptions Browser = new();
+
+	[Test]
+	public async Task Resolve_Plain_ForNoMarkup()
+	{
+		await Assert.That(AnsiDisplay.Default.Resolve(null, Browser)).IsEqualTo(DisplayStyle.Plain);
+	}
+
+	[Test]
+	public async Task Resolve_PlainTextOutput_DropsEverything()
+	{
+		var options = new DisplayOptions { Capabilities = OutputCapabilities.PlainText };
+		var style = AnsiDisplay.Default.Resolve(MarkupSet.Of([Red, Link]), options);
+		await Assert.That(style).IsEqualTo(DisplayStyle.Plain);
+	}
+
+	[Test]
+	public async Task Resolve_PromptBecomesCommand_WhenPromptsAreNotShown()
+	{
+		var menu = new CommandMenuMarkup([new CommandChoice("look", "look")], Prompt: false);
+		var options = new DisplayOptions { Capabilities = OutputCapabilities.Browser with { Interactions = InteractionKinds.Command } };
+		var style = AnsiDisplay.Default.Resolve(MarkupSet.Of(menu), options);
+		await Assert.That(style.Interaction!.Kind).IsEqualTo(InteractionKind.Command);
+		await Assert.That(style.Interaction.Choices).IsNull();
+	}
+
+	[Test]
+	public async Task Resolve_Menu_KeepsChoices()
+	{
+		var menu = new CommandMenuMarkup([new CommandChoice("Buy", "buy sword"), new CommandChoice("Look", "look sword")], "Sword");
+		var style = AnsiDisplay.Default.Resolve(MarkupSet.Of(menu), Browser);
+		await Assert.That(style.Interaction!.Target).IsEqualTo("buy sword");
+		await Assert.That(style.Interaction.Hint).IsEqualTo("Sword");
+		await Assert.That(style.Interaction.Choices!.Count).IsEqualTo(2);
+	}
+
+	[Test]
+	public async Task Resolve_Highlight_WinsOverAnsiBackground()
+	{
+		var background = AnsiMarkup.Create(background: new AnsiColor.Standard(4, false));
+		var style = AnsiDisplay.Default.Resolve(MarkupSet.Of([new HighlightMarkup(new RgbColor(255, 255, 0)), background]), Browser);
+		await Assert.That(style.Background).IsEqualTo(new RgbColor(255, 255, 0));
+	}
+
+	[Test]
+	public async Task Resolve_InnerColourWins()
+	{
+		var green = AnsiMarkup.Create(foreground: new AnsiColor.Standard(2, false));
+		var style = AnsiDisplay.Default.Resolve(MarkupSet.Of([green, Red]), Browser);
+		await Assert.That(style.Foreground).IsEqualTo(new RgbColor(0, 170, 0));
+	}
+
+	[Test]
+	public async Task BoldIsBright()
+	{
+		var registry = DisplayRegistry.Core.WithAnsi(boldIsBright: true);
+		var style = registry.Resolve(MarkupSet.Of(AnsiMarkup.Create(foreground: new AnsiColor.Standard(1, false), bold: true)), Browser);
+		await Assert.That(style.Foreground).IsEqualTo(new RgbColor(255, 85, 85));
+	}
+
+	[Test]
+	public async Task Spans_MergeEqualStyles()
+	{
+		var text = MarkupText.Concat([MarkupText.Wrap(Red, "a"), MarkupText.Wrap(AnsiMarkup.Create(foreground: new AnsiColor.Xterm(1)), "b"), MarkupText.Plain("c")]);
+		var spans = SpanRenderer.Render(text, AnsiDisplay.Default, Browser);
+		await Assert.That(spans.Select(span => span.Text)).IsEquivalentTo(["ab", "c"]);
+	}
+
+	[Test]
+	public async Task Spans_AsciiOutput_FoldsText()
+	{
+		var options = new DisplayOptions { Capabilities = OutputCapabilities.Browser with { Unicode = UnicodeLevel.Ascii } };
+		var spans = SpanRenderer.Render(MarkupText.Plain("café"), AnsiDisplay.Default, options);
+		await Assert.That(spans.Single().Text).IsEqualTo("cafe");
+	}
+
+	[Test]
+	public async Task Spans_Sound_DroppedWithoutSound()
+	{
+		var text = MarkupText.Concat([MarkupText.Plain("a"), MarkupText.Sound("boom.wav")]);
+		var options = new DisplayOptions { Capabilities = OutputCapabilities.Browser with { Sound = false } };
+		await Assert.That(SpanRenderer.Render(text, AnsiDisplay.Default, options).Count).IsEqualTo(1);
+		await Assert.That(SpanRenderer.Render(text, AnsiDisplay.Default, Browser)[^1].Point).IsTypeOf<SoundMarkup>();
+	}
+
+	[Test]
+	public async Task Css_And_Classes()
+	{
+		var style = new DisplayStyle
+		{
+			Foreground = new RgbColor(255, 0, 0),
+			Attributes = TextAttributes.Bold | TextAttributes.Underline | TextAttributes.Strikethrough | TextAttributes.Blink,
+			Interaction = new Interaction(InteractionKind.Command, "look"),
+		};
+		await Assert.That(SpanRenderer.Css(style)).IsEqualTo("color:#ff0000;font-weight:bold;text-decoration:underline line-through");
+		await Assert.That(SpanRenderer.CssClasses(style)).IsEqualTo("ms-blink ms-command");
+	}
+
+	[Test]
+	public async Task Cells_WideCharacters_TakeTwoCells()
+	{
+		var layout = CellRenderer.Layout(MarkupText.Plain("a漢b"), 0, AnsiDisplay.Default, Browser);
+		var cells = layout.Rows.Single().Cells;
+		await Assert.That(cells.Select(cell => cell.Text)).IsEquivalentTo(["a", "漢", "", "b"]);
+		await Assert.That(cells[2].IsContinuation).IsTrue();
+	}
+
+	[Test]
+	public async Task Cells_WrapAtTheWidth()
+	{
+		var layout = CellRenderer.Layout(MarkupText.Plain("abcdefg"), 3, AnsiDisplay.Default, Browser);
+		await Assert.That(layout.Rows.Select(row => string.Concat(row.Cells.Select(cell => cell.Text)))).IsEquivalentTo(["abc", "def", "g"]);
+		await Assert.That(layout.Rows.Select(row => row.Wrapped)).IsEquivalentTo([true, true, false]);
+	}
+
+	[Test]
+	public async Task Cells_WideCharacterDoesNotSplit()
+	{
+		var layout = CellRenderer.Layout(MarkupText.Plain("ab漢"), 3, AnsiDisplay.Default, Browser);
+		await Assert.That(layout.Rows.Select(row => string.Concat(row.Cells.Select(cell => cell.Text)))).IsEquivalentTo(["ab", "漢"]);
+	}
+
+	[Test]
+	public async Task Cells_WordWrap()
+	{
+		var layout = CellRenderer.Layout(MarkupText.Plain("the quick fox"), 10, AnsiDisplay.Default, Browser, wordWrap: true);
+		await Assert.That(layout.Rows.Select(row => string.Concat(row.Cells.Select(cell => cell.Text)))).IsEquivalentTo(["the quick ", "fox"]);
+	}
+
+	[Test]
+	public async Task Cells_LineFeed_StartsARow()
+	{
+		var layout = CellRenderer.Layout(MarkupText.Plain("a\nb"), 0, AnsiDisplay.Default, Browser);
+		await Assert.That(layout.Rows.Count).IsEqualTo(2);
+		await Assert.That(layout.Rows[0].Wrapped).IsFalse();
+	}
+
+	[Test]
+	public async Task Cells_Tab_AdvancesToTheStop()
+	{
+		var layout = CellRenderer.Layout(MarkupText.Plain("ab\tc"), 0, AnsiDisplay.Default, new DisplayOptions { TabWidth = 4 });
+		await Assert.That(layout.Rows[0].Cells.Count).IsEqualTo(5);
+		await Assert.That(layout.Rows[0].Cells[4].Text).IsEqualTo("c");
+	}
+
+	[Test]
+	public async Task Cells_HitTest_FindsTheLink()
+	{
+		var text = MarkupText.Concat([MarkupText.Plain("go "), MarkupText.Wrap(Link, "漢")]);
+		var layout = CellRenderer.Layout(text, 0, AnsiDisplay.Default, Browser);
+		await Assert.That(layout.InteractionAt(0, 0)).IsNull();
+		await Assert.That(layout.InteractionAt(0, 3)!.Target).IsEqualTo("look");
+		await Assert.That(layout.InteractionAt(0, 4)!.Target).IsEqualTo("look");
+		await Assert.That(layout.InteractionAt(0, 5)).IsNull();
+	}
+
+	[Test]
+	public async Task Cells_PictureColumns_CountFromTheFirstShown()
+	{
+		var picture = new ImageMarkup("cat.png") { Row = new PictureRow(0, 2, 3) { FirstColumn = 1 } };
+		var layout = CellRenderer.Layout(MarkupText.Wrap(picture, "   "), 0, AnsiDisplay.Default, Browser);
+		await Assert.That(layout.Rows[0].Cells.Select(cell => cell.PictureColumn)).IsEquivalentTo([1, 2, 3]);
+	}
+
+	[Test]
+	public async Task Cells_PicturesDropped_WhenNotShown()
+	{
+		var picture = new ImageMarkup("cat.png") { Row = new PictureRow(0, 1, 2) };
+		var options = new DisplayOptions { Capabilities = OutputCapabilities.PlainText };
+		var layout = CellRenderer.Layout(MarkupText.Wrap(picture, "  "), 0, AnsiDisplay.Default, options);
+		await Assert.That(layout.Rows[0].Cells[0].Style.Picture).IsNull();
+	}
+
+	[Test]
+	public async Task MenuMarkup_RoundTripsThroughJson()
+	{
+		var menu = new CommandMenuMarkup([new CommandChoice("Buy", "buy"), new CommandChoice("Look", "look")], "hint", Prompt: true);
+		var text = MarkupText.Wrap(new HighlightMarkup(new RgbColor(1, 2, 3)), MarkupText.Wrap(menu, "sword"));
+		var json = MarkupTextSerializer.Serialize(text);
+		var back = MarkupTextSerializer.Deserialize(json);
+		await Assert.That(back.Runs.Single().Markups).IsEqualTo(text.Runs.Single().Markups);
+	}
+}
diff --git a/MarkupString.Tests/Decoding/VtDecodingTests.cs b/MarkupString.Tests/Decoding/VtDecodingTests.cs
new file mode 100644
index 0000000..ad5699e
--- /dev/null
+++ b/MarkupString.Tests/Decoding/VtDecodingTests.cs
@@ -0,0 +1,311 @@
+using MarkupString.Ansi;
+using MarkupString.Ansi.Decoding;
+using MarkupString.Decoding;
+using MarkupString.Display;
+
+public class VtDecodingTests
+{
+	private static readonly DisplayOptions Options = new();
+
+	private static IReadOnlyList<DisplayLine> Decode(string text, DecoderOptions? options = null) =>
+		Decoder.DecodeAll(text, VtDecoding.Terminal, options);
+
+	private static IReadOnlyList<DisplaySpan> Spans(MarkupText text) => SpanRenderer.Render(text, AnsiDisplay.Default, Options);
+
+	private static DisplaySpan Only(string text)
+	{
+		var lines = Decode(text);
+		var spans = Spans(lines[0].Content);
+		return spans.Single(span => span.Text.Trim().Length > 0);
+	}
+
+	[Test]
+	public async Task LineFeeds_SplitLines()
+	{
+		var lines = Decode("one\ntwo\r\nthree");
+		await Assert.That(lines.Select(line => line.Content.ToPlainText())).IsEquivalentTo(["one", "two", "three"]);
+		await Assert.That(lines.Select(line => line.Sequence)).IsEquivalentTo([0L, 1L, 2L]);
+	}
+
+	[Test]
+	public async Task Prompt_EndsWithoutALineFeed()
+	{
+		var decoder = VtDecoding.Terminal.CreateDecoder();
+		await Assert.That(decoder.Feed("Name: ")).IsEmpty();
+		var prompt = decoder.EndPrompt();
+		await Assert.That(prompt!.Kind).IsEqualTo(LineKind.Prompt);
+		await Assert.That(prompt.Content.ToPlainText()).IsEqualTo("Name: ");
+		await Assert.That(decoder.EndPrompt()).IsNull();
+	}
+
+	[Test]
+	public async Task CarriageReturn_OverwritesTheLine()
+	{
+		var lines = Decode("[    ] 0%\r[##  ] 50%\r[####] 100%\n");
+		await Assert.That(lines.Single().Content.ToPlainText()).IsEqualTo("[####] 100%");
+	}
+
+	[Test]
+	public async Task CarriageReturn_ShorterText_KeepsTheRest()
+	{
+		var lines = Decode("abcdef\rXY\n");
+		await Assert.That(lines.Single().Content.ToPlainText()).IsEqualTo("XYcdef");
+	}
+
+	[Test]
+	public async Task EraseToEndOfLine_AfterCarriageReturn()
+	{
+		var lines = Decode("abcdef\rXY\e[K\n");
+		await Assert.That(lines.Single().Content.ToPlainText()).IsEqualTo("XY");
+	}
+
+	[Test]
+	public async Task Backspace_Overwrites()
+	{
+		var lines = Decode("ab\bc\n");
+		await Assert.That(lines.Single().Content.ToPlainText()).IsEqualTo("ac");
+	}
+
+	[Test]
+	public async Task Tab_PadsToTheNextStop()
+	{
+		var lines = Decode("ab\tc\n");
+		await Assert.That(lines.Single().Content.ToPlainText()).IsEqualTo("ab      c");
+	}
+
+	[Test]
+	public async Task Overwrite_KeepsStyleOfWhatIsLeft()
+	{
+		var lines = Decode("\e[31mred\e[0m\rX\n");
+		var spans = Spans(lines.Single().Content);
+		await Assert.That(spans.Select(span => span.Text)).IsEquivalentTo(["X", "ed"]);
+		await Assert.That(spans[1].Style.Foreground).IsEqualTo(new RgbColor(170, 0, 0));
+	}
+
+	[Test]
+	public async Task Sgr_StandardColour()
+	{
+		var span = Only("\e[1;32mgo\e[0m\n");
+		await Assert.That(span.Style.Foreground).IsEqualTo(new RgbColor(0, 170, 0));
+		await Assert.That(span.Style.Has(TextAttributes.Bold)).IsTrue();
+	}
+
+	[Test]
+	public async Task Sgr_TrueColour_SemicolonsAndColons()
+	{
+		await Assert.That(Only("\e[38;2;1;2;3mx\n").Style.Foreground).IsEqualTo(new RgbColor(1, 2, 3));
+		await Assert.That(Only("\e[38:2::4:5:6mx\n").Style.Foreground).IsEqualTo(new RgbColor(4, 5, 6));
+		await Assert.That(Only("\e[48:2:7:8:9mx\n").Style.Background).IsEqualTo(new RgbColor(7, 8, 9));
+	}
+
+	[Test]
+	public async Task Sgr_Xterm256()
+	{
+		await Assert.That(Only("\e[38;5;196mx\n").Style.Foreground).IsEqualTo(new RgbColor(255, 0, 0));
+	}
+
+	[Test]
+	public async Task Sgr_UnderlineStyleSubparameter_IsStillUnderline()
+	{
+		await Assert.That(Only("\e[4:3mx\n").Style.Has(TextAttributes.Underline)).IsTrue();
+		var off = Decode("\e[4m\e[4:0mx\n");
+		await Assert.That(Spans(off[0].Content).Single().Style.Has(TextAttributes.Underline)).IsFalse();
+	}
+
+	[Test]
+	public async Task Sgr_Conceal()
+	{
+		await Assert.That(Only("\e[8msecret\n").Style.Has(TextAttributes.Conceal)).IsTrue();
+	}
+
+	[Test]
+	public async Task Sgr_Reset_ClearsEverything()
+	{
+		var lines = Decode("\e[1;31ma\e[mb\n");
+		var spans = Spans(lines[0].Content);
+		await Assert.That(spans[1].Text).IsEqualTo("b");
+		await Assert.That(spans[1].Style).IsEqualTo(DisplayStyle.Plain);
+	}
+
+	[Test]
+	public async Task Sgr_RoundTripsToAnsi()
+	{
+		var lines = Decode("\e[1;31mhi\e[0m there\n");
+		var ansi = lines[0].Content.Render(MarkupFormat.Ansi, MarkupRegistry.Empty.WithAnsi());
+		await Assert.That(ansi).IsEqualTo("\e[1;31mhi\e[0m there");
+	}
+
+	[Test]
+	public async Task Sgr_StyleCarriesAcrossLines()
+	{
+		var lines = Decode("\e[34mone\ntwo\e[0m\n");
+		await Assert.That(Spans(lines[1].Content).Single().Style.Foreground).IsEqualTo(new RgbColor(0, 0, 170));
+	}
+
+	[Test]
+	public async Task Inverse_SwapsColours()
+	{
+		var style = Only("\e[7;31mx\n").Style;
+		await Assert.That(style.Foreground).IsEqualTo(Options.DefaultBackground);
+		await Assert.That(style.Background).IsEqualTo(new RgbColor(170, 0, 0));
+	}
+
+	[Test]
+	public async Task Osc8_MakesALink()
+	{
+		var lines = Decode("see \e]8;;https://example.com\e\\here\e]8;;\e\\ ok\n");
+		var spans = Spans(lines[0].Content);
+		await Assert.That(spans.Select(span => span.Text)).IsEquivalentTo(["see ", "here", " ok"]);
+		await Assert.That(spans[1].Style.Interaction).IsEqualTo(new Interaction(InteractionKind.Url, "https://example.com"));
+		await Assert.That(spans[2].Style.Interaction).IsNull();
+	}
+
+	[Test]
+	public async Task Osc8_UnsafeScheme_IsText()
+	{
+		var lines = Decode("\e]8;;javascript:alert(1)\e\\x\e]8;;\e\\\n");
+		await Assert.That(Spans(lines[0].Content).Single().Style.Interaction).IsNull();
+	}
+
+	[Test]
+	public async Task Mslp_LinkLastsAsLongAsTheUnderline()
+	{
+		var lines = Decode("\e]68;1;SEND;look\a\e[4mlook\e[24m here\n");
+		var spans = Spans(lines[0].Content);
+		await Assert.That(spans[0].Text).IsEqualTo("look");
+		await Assert.That(spans[0].Style.Interaction).IsEqualTo(new Interaction(InteractionKind.Command, "look"));
+		await Assert.That(spans[1].Style.Interaction).IsNull();
+	}
+
+	[Test]
+	public async Task Mslp_RoundTripsThroughTheAnsiWriter()
+	{
+		var link = MarkupText.Wrap(new AnsiMarkup(new AnsiStyle { LinkUrl = "look", LinkKind = LinkKind.Command }), "look");
+		var registry = MarkupRegistry.Empty.WithAnsiOutput(new AnsiOutputOptions { Features = TerminalFeatures.CommandLinks });
+		var wire = link.Render(MarkupFormat.Ansi, registry);
+		var spans = Spans(Decode(wire + "\n")[0].Content);
+		await Assert.That(spans.Single().Style.Interaction).IsEqualTo(new Interaction(InteractionKind.Command, "look"));
+	}
+
+	[Test]
+	public async Task DecSpecialGraphics_DrawsBoxes()
+	{
+		var lines = Decode("\e(0lqk\e(B ok\n");
+		await Assert.That(lines[0].Content.ToPlainText()).IsEqualTo("┌─┐ ok");
+	}
+
+	[Test]
+	public async Task ShiftOut_UsesG1()
+	{
+		var lines = Decode("\e)0a\u000eqx\u000fq\n");
+		await Assert.That(lines[0].Content.ToPlainText()).IsEqualTo("a─│q");
+	}
+
+	[Test]
+	public async Task Bell_IsAPoint()
+	{
+		var lines = Decode("ding\a\n");
+		var spans = Spans(lines[0].Content);
+		await Assert.That(spans[^1].Point).IsSameReferenceAs(BellMarkup.Instance);
+		await Assert.That(lines[0].Content.ToPlainText()).IsEqualTo("ding");
+	}
+
+	[Test]
+	public async Task Title_Palette_Clipboard_AreEvents()
+	{
+		var decoder = VtDecoding.Terminal.CreateDecoder();
+		var events = new List<DecodeEvent>();
+		decoder.EventRaised += events.Add;
+		decoder.Feed("\e]2;The Game\a\e]4;1;rgb:ff/00/80\a\e]11;#102030\a\e]104\a\e]52;c;aGk=\a");
+		await Assert.That(events).IsEquivalentTo(new DecodeEvent[]
+		{
+			new TitleEvent("The Game", false),
+			new PaletteEvent(PaletteSlot.Index, 1, new RgbColor(255, 0, 128)),
+			new PaletteEvent(PaletteSlot.Background, 0, new RgbColor(16, 32, 48)),
+			new PaletteEvent(PaletteSlot.Index, -1, null),
+			new ClipboardEvent("c", "hi"),
+		});
+	}
+
+	[Test]
+	public async Task ColorSpec_ScalesChannels()
+	{
+		await Assert.That(OscPlugin.ParseColor("rgb:f/8/0")).IsEqualTo(new RgbColor(255, 136, 0));
+		await Assert.That(OscPlugin.ParseColor("rgb:ffff/0000/8080")).IsEqualTo(new RgbColor(255, 0, 128));
+		await Assert.That(OscPlugin.ParseColor("#fff")).IsEqualTo(new RgbColor(255, 255, 255));
+		await Assert.That(OscPlugin.ParseColor("red")).IsNull();
+	}
+
+	[Test]
+	public async Task Answers_FromTheIdentity()
+	{
+		var identity = new ClientIdentity { Name = "TestClient", Version = "2.1", Columns = 100, Rows = 30, Foreground = new RgbColor(1, 2, 3) };
+		var decoder = VtDecoding.Terminal.CreateDecoder(new DecoderOptions { Identity = identity });
+		var replies = new List<string>();
+		decoder.EventRaised += e => { if (e is ReplyEvent reply) replies.Add(reply.Text); };
+		decoder.Feed("\e[c\e[>q\e[18t\e[16t\e]10;?\a\e[6n");
+		await Assert.That(replies).IsEquivalentTo([
+			"\e[?62;22c",
+			"\eP>|TestClient 2.1\e\\",
+			"\e[8;30;100t",
+			"\e[6;16;8t",
+			"\e]10;rgb:0101/0202/0303\e\\",
+		]);
+	}
+
+	[Test]
+	public async Task Answers_CursorPosition_WhenAllowed()
+	{
+		var identity = new ClientIdentity { Answers = ClientAnswers.Default | ClientAnswers.CursorPosition };
+		var decoder = VtDecoding.Terminal.CreateDecoder(new DecoderOptions { Identity = identity });
+		var replies = new List<string>();
+		decoder.EventRaised += e => { if (e is ReplyEvent reply) replies.Add(reply.Text); };
+		decoder.Feed("abc\e[6n");
+		await Assert.That(replies).IsEquivalentTo(["\e[24;4R"]);
+	}
+
+	[Test]
+	public async Task Answers_None_WhenTurnedOff()
+	{
+		var decoder = VtDecoding.Terminal.CreateDecoder(new DecoderOptions { Identity = new ClientIdentity { Answers = ClientAnswers.None } });
+		var replies = 0;
+		decoder.EventRaised += e => { if (e is ReplyEvent) replies++; };
+		decoder.Feed("\e[c\e[>q\e[18t");
+		await Assert.That(replies).IsEqualTo(0);
+		await Assert.That(decoder.Diagnostics.UnhandledSequences).IsEqualTo(0);
+	}
+
+	[Test]
+	public async Task Unknown_IsCounted()
+	{
+		var decoder = VtDecoding.Terminal.CreateDecoder();
+		decoder.Feed("\e[5;5H\e]777;x\a");
+		await Assert.That(decoder.Diagnostics.UnhandledSequences).IsEqualTo(2);
+	}
+
+	[Test]
+	public async Task LineLength_IsCapped()
+	{
+		var decoder = VtDecoding.Terminal.CreateDecoder(new DecoderOptions { MaxLineLength = 4 });
+		decoder.Feed("abc");
+		decoder.Feed("def");
+		await Assert.That(decoder.EndLine().Content.ToPlainText()).IsEqualTo("abc");
+		await Assert.That(decoder.Diagnostics.LimitsReached).IsEqualTo(1);
+	}
+
+	[Test]
+	public async Task ClearScreen_IsAPoint()
+	{
+		var lines = Decode("\e[2Jtop\n");
+		await Assert.That(lines[0].Content.Runs[0].Markups.Innermost).IsSameReferenceAs(ClearScreenMarkup.Instance);
+	}
+
+	[Test]
+	public async Task Capabilities_FromAProfile()
+	{
+		var capabilities = TerminalProfile.Kitty.ToOutputCapabilities(AnsiColorDepth.TrueColor);
+		await Assert.That(capabilities.Pictures).IsEqualTo(PictureMethods.KittyPlaceholders | PictureMethods.HalfBlocks);
+		await Assert.That(capabilities.Interactions).IsEqualTo(InteractionKinds.Url);
+		await Assert.That(capabilities.ToTerminalFeatures() & TerminalFeatures.Pictures).IsEqualTo(TerminalFeatures.KittyGraphics | TerminalFeatures.BlockArt);
+	}
+}
diff --git a/MarkupString.Tests/Decoding/VtTokenizerTests.cs b/MarkupString.Tests/Decoding/VtTokenizerTests.cs
new file mode 100644
index 0000000..f3cb699
--- /dev/null
+++ b/MarkupString.Tests/Decoding/VtTokenizerTests.cs
@@ -0,0 +1,120 @@
+using MarkupString.Decoding;
+
+public class VtTokenizerTests
+{
+	private sealed class Recorder : IVtTokenSink
+	{
+		public List<string> Tokens { get; } = [];
+
+		public void Print(ReadOnlySpan<char> text) => Add($"print:{text}");
+
+		public void Execute(char control) => Add($"exec:{(int)control}");
+
+		public void Csi(in CsiSequence sequence)
+		{
+			var parameters = new List<string>();
+			for (var i = 0; i < sequence.Count; i++)
+			{
+				parameters.Add((sequence.IsSubparameter(i) ? ":" : "") + sequence.Parameters[i]);
+			}
+
+			Tokens.Add($"csi:{(sequence.Prefix == '\0' ? "" : sequence.Prefix.ToString())}{string.Join(",", parameters)}{sequence.Intermediates}{sequence.Final}");
+		}
+
+		public void Esc(in EscSequence sequence) => Tokens.Add($"esc:{sequence.Intermediates}{sequence.Final}");
+
+		public void Osc(ReadOnlySpan<char> payload) => Tokens.Add($"osc:{payload}");
+
+		public void Dcs(in CsiSequence header, ReadOnlySpan<char> data) => Tokens.Add($"dcs:{header.Final}:{data}");
+
+		public void Apc(ReadOnlySpan<char> payload) => Tokens.Add($"apc:{payload}");
+
+		public void Abandoned(VtSequenceKind kind) => Tokens.Add($"abandoned:{kind}");
+
+		private void Add(string token)
+		{
+			// Print may arrive in pieces; join neighbours so tests read the text whole.
+			if (token.StartsWith("print:", StringComparison.Ordinal) && Tokens.Count > 0 && Tokens[^1].StartsWith("print:", StringComparison.Ordinal))
+			{
+				Tokens[^1] += token["print:".Length..];
+				return;
+			}
+
+			Tokens.Add(token);
+		}
+	}
+
+	private static List<string> Tokens(params string[] chunks)
+	{
+		var tokenizer = new VtTokenizer(VtLimits.Default);
+		var sink = new Recorder();
+		foreach (var chunk in chunks) tokenizer.Feed(chunk, sink);
+		return sink.Tokens;
+	}
+
+	[Test]
+	public async Task Csi_WithParameters_IsOneToken()
+	{
+		await Assert.That(Tokens("a\e[1;31mb")).IsEquivalentTo(["print:a", "csi:1,31m", "print:b"]);
+	}
+
+	[Test]
+	public async Task Csi_SplitAcrossFeeds_IsStillOneToken()
+	{
+		await Assert.That(Tokens("\e[3", "8;5;2", "08mx")).IsEquivalentTo(["csi:38,5,208m", "print:x"]);
+	}
+
+	[Test]
+	public async Task Csi_ColonSubparameters_AreMarked()
+	{
+		await Assert.That(Tokens("\e[38:2::10:20:30m")).IsEquivalentTo(["csi:38,:2,:-1,:10,:20,:30m"]);
+	}
+
+	[Test]
+	public async Task Csi_PrivatePrefix_IsKept()
+	{
+		await Assert.That(Tokens("\e[>q")).IsEquivalentTo(["csi:>q"]);
+	}
+
+	[Test]
+	public async Task Osc_EndsAtBelOrSt()
+	{
+		await Assert.That(Tokens("\e]2;one\a\e]2;two\e\\")).IsEquivalentTo(["osc:2;one", "osc:2;two"]);
+	}
+
+	[Test]
+	public async Task Apc_EndsAtSt()
+	{
+		await Assert.That(Tokens("\e_Ga=q;AAAA\e\\z")).IsEquivalentTo(["apc:Ga=q;AAAA", "print:z"]);
+	}
+
+	[Test]
+	public async Task Dcs_CarriesItsData()
+	{
+		await Assert.That(Tokens("\eP0;1q#0~-\e\\")).IsEquivalentTo(["dcs:q:#0~-"]);
+	}
+
+	[Test]
+	public async Task LineFeed_AbandonsAnOpenSequence_ThenEndsTheLine()
+	{
+		await Assert.That(Tokens("\e[31\nok")).IsEquivalentTo(["abandoned:Csi", "exec:10", "print:ok"]);
+	}
+
+	[Test]
+	public async Task Cancel_AbandonsTheSequence()
+	{
+		await Assert.That(Tokens("\e[31\u0018ok")).IsEquivalentTo(["abandoned:Csi", "print:ok"]);
+	}
+
+	[Test]
+	public async Task Esc_WithIntermediate()
+	{
+		await Assert.That(Tokens("\e(0q\e(B")).IsEquivalentTo(["esc:(0", "print:q", "esc:(B"]);
+	}
+
+	[Test]
+	public async Task C0Controls_AreExecuted()
+	{
+		await Assert.That(Tokens("a\rb\bc\a")).IsEquivalentTo(["print:a", "exec:13", "print:b", "exec:8", "print:c", "exec:7"]);
+	}
+}

From d5df55575d506ffb9713c346e4a72c272ed94577 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 21:56:00 +0000
Subject: [PATCH 07/19] Decode Kitty, iTerm2 and sixel pictures into a picture
 store

---
 MarkupString.Ansi/Decoding/PictureStore.cs    | 160 ++++
 MarkupString.Ansi/Decoding/PicturesPlugin.cs  | 751 ++++++++++++++++++
 MarkupString.Ansi/Decoding/PngDecoder.cs      | 260 ++++++
 MarkupString.Ansi/Decoding/SixelDecoder.cs    | 246 ++++++
 MarkupString.Ansi/Decoding/VtPlugins.cs       |  26 +-
 .../Emitters/TerminalPictureWriter.cs         |   4 +-
 MarkupString.Ansi/PublicAPI.Unshipped.txt     |  36 +
 .../Decoding/PictureDecodingTests.cs          | 238 ++++++
 MarkupString/Decoding/Decoder.cs              |  13 +-
 MarkupString/PublicAPI.Unshipped.txt          |   6 +
 README.md                                     |   2 +
 docs/decoding.md                              | 465 +++++++++++
 docs/display.md                               | 338 ++++++++
 13 files changed, 2536 insertions(+), 9 deletions(-)
 create mode 100644 MarkupString.Ansi/Decoding/PictureStore.cs
 create mode 100644 MarkupString.Ansi/Decoding/PicturesPlugin.cs
 create mode 100644 MarkupString.Ansi/Decoding/PngDecoder.cs
 create mode 100644 MarkupString.Ansi/Decoding/SixelDecoder.cs
 create mode 100644 MarkupString.Tests/Decoding/PictureDecodingTests.cs
 create mode 100644 docs/decoding.md
 create mode 100644 docs/display.md

diff --git a/MarkupString.Ansi/Decoding/PictureStore.cs b/MarkupString.Ansi/Decoding/PictureStore.cs
new file mode 100644
index 0000000..fe27878
--- /dev/null
+++ b/MarkupString.Ansi/Decoding/PictureStore.cs
@@ -0,0 +1,160 @@
+using System.Diagnostics.CodeAnalysis;
+using System.Security.Cryptography;
+namespace MarkupString.Ansi.Decoding;
+
+/// <summary>
+/// A picture a decoder read from the server: its pixels when it could decode them, and the file as it came when
+/// there was one. <see cref="ImageMarkup"/>s refer to it by <see cref="Source"/>.
+/// </summary>
+public sealed class StoredPicture
+{
+	private ReadOnlyMemory<byte> _encoded;
+
+	internal StoredPicture(string key, int width, int height, TerminalPicture? pixels, ReadOnlyMemory<byte> encoded, string? mediaType)
+	{
+		Key = key;
+		Width = width;
+		Height = height;
+		Pixels = pixels;
+		_encoded = encoded;
+		MediaType = encoded.IsEmpty ? null : mediaType;
+	}
+
+	/// <summary>What identifies it: a hash of its contents, so the same picture sent twice is stored once.</summary>
+	public string Key { get; }
+
+	/// <summary>Its width in pixels.</summary>
+	public int Width { get; }
+
+	/// <summary>Its height in pixels.</summary>
+	public int Height { get; }
+
+	/// <summary>Its pixels, or null for a file this package cannot decode (a JPEG, a GIF), which only a browser can show.</summary>
+	public TerminalPicture? Pixels { get; }
+
+	/// <summary>The file's media type, such as <c>image/png</c>, or null when the server sent bare pixels.</summary>
+	public string? MediaType { get; }
+
+	/// <summary>What an <see cref="ImageMarkup.Source"/> that shows it says: <c>picture:</c> and the key.</summary>
+	public string Source => PictureStore.Scheme + Key;
+
+	/// <summary>How many bytes it holds.</summary>
+	public long Size => _encoded.Length + (Pixels?.Rgba.Length ?? 0);
+
+	/// <summary>The file as the server sent it, or, for bare pixels, the pixels as a PNG.</summary>
+	public ReadOnlyMemory<byte> Encoded
+	{
+		get
+		{
+			if (_encoded.IsEmpty && Pixels is { } pixels) _encoded = PngWriter.Encode(pixels.Rgba.Span, pixels.Width, pixels.Height);
+			return _encoded;
+		}
+	}
+
+	/// <summary>The picture as a <c>data:</c> address, for an <c>&lt;img&gt;</c>.</summary>
+	public string ToDataUrl() => $"data:{MediaType ?? "image/png"};base64,{Convert.ToBase64String(Encoded.Span)}";
+}
+
+/// <summary>
+/// The pictures one connection's decoder read, within a budget of bytes; the least recently used go first. It is
+/// also the <see cref="ITerminalPictureSource"/> that draws them again in a terminal. Get a decoder's with
+/// <see cref="PicturesPlugin.Pictures(MarkupString.Decoding.Decoder)"/>.
+/// </summary>
+/// <remarks>
+/// A picture the server deletes (Kitty <c>a=d</c>) is only forgotten by its id: lines already read still show it,
+/// until the budget pushes it out. A line whose picture is gone shows its text instead.
+/// </remarks>
+public sealed class PictureStore : ITerminalPictureSource
+{
+	/// <summary>The scheme of a <see cref="StoredPicture.Source"/>.</summary>
+	public const string Scheme = "picture:";
+
+	private readonly Dictionary<string, LinkedListNode<StoredPicture>> _pictures = new(StringComparer.Ordinal);
+	private readonly LinkedList<StoredPicture> _order = [];
+	private readonly HashSet<uint> _transmitted = [];
+
+	/// <summary>The most bytes held. 64 MiB unless set.</summary>
+	public long Budget { get; set; } = 64L * 1024 * 1024;
+
+	/// <summary>The largest picture decoded, in pixels.</summary>
+	public long MaxPixels { get; set; } = 4096L * 4096;
+
+	/// <summary>The bytes held now.</summary>
+	public long Used { get; private set; }
+
+	/// <summary>The pictures held now.</summary>
+	public int Count => _pictures.Count;
+
+	/// <summary>Raised when a picture is stored, so a host can serve it from an address of its own.</summary>
+	public event Action<StoredPicture>? Added;
+
+	/// <summary>Stores decoded pixels.</summary>
+	public StoredPicture Add(int width, int height, byte[] rgba) => Add(width, height, rgba, default, null);
+
+	/// <summary>Stores a file, with its pixels when they were decoded.</summary>
+	public StoredPicture Add(int width, int height, byte[]? rgba, ReadOnlyMemory<byte> encoded, string? mediaType)
+	{
+		var key = Hash(encoded.IsEmpty ? rgba : encoded.Span);
+		if (_pictures.TryGetValue(key, out var existing))
+		{
+			_order.Remove(existing);
+			_order.AddFirst(existing);
+			return existing.Value;
+		}
+
+		var pixels = rgba is null ? null : new TerminalPicture(key, width, height, rgba);
+		var picture = new StoredPicture(key, width, height, pixels, encoded, mediaType);
+		_pictures[key] = _order.AddFirst(picture);
+		Used += picture.Size;
+		while (Used > Budget && _order.Count > 1) Remove(_order.Last!.Value.Key);
+		Added?.Invoke(picture);
+		return picture;
+	}
+
+	/// <summary>The picture with <paramref name="key"/>, if it is still held.</summary>
+	public bool TryGet(string key, [NotNullWhen(true)] out StoredPicture? picture)
+	{
+		if (_pictures.TryGetValue(key, out var node))
+		{
+			picture = node.Value;
+			return true;
+		}
+
+		picture = null;
+		return false;
+	}
+
+	/// <summary>The picture <paramref name="image"/> shows, if it is one of these and still held.</summary>
+	public bool TryGet(ImageMarkup image, [NotNullWhen(true)] out StoredPicture? picture)
+	{
+		ArgumentNullException.ThrowIfNull(image);
+		picture = null;
+		return image.Source.StartsWith(Scheme, StringComparison.Ordinal) && TryGet(image.Source[Scheme.Length..], out picture);
+	}
+
+	/// <summary>Forgets the picture with <paramref name="key"/>.</summary>
+	public bool Remove(string key)
+	{
+		if (!_pictures.Remove(key, out var node)) return false;
+		_order.Remove(node);
+		Used -= node.Value.Size;
+		return true;
+	}
+
+	/// <inheritdoc/>
+	public bool TryGetPicture(ImageMarkup image, [NotNullWhen(true)] out TerminalPicture? picture)
+	{
+		picture = TryGet(image, out var stored) ? stored.Pixels : null;
+		return picture is not null;
+	}
+
+	/// <inheritdoc/>
+	public bool MarkTransmitted(uint imageId) => _transmitted.Add(imageId);
+
+	private static string Hash(ReadOnlySpan<byte> data)
+	{
+		Span<byte> hash = stackalloc byte[32];
+		SHA256.HashData(data, hash);
+		return Convert.ToHexStringLower(hash[..12]);
+	}
+}
diff --git a/MarkupString.Ansi/Decoding/PicturesPlugin.cs b/MarkupString.Ansi/Decoding/PicturesPlugin.cs
new file mode 100644
index 0000000..aeb6404
--- /dev/null
+++ b/MarkupString.Ansi/Decoding/PicturesPlugin.cs
@@ -0,0 +1,751 @@
+using System.Buffers.Binary;
+using System.Globalization;
+using System.IO.Compression;
+using System.Text;
+using MarkupString.Decoding;
+using Decoder = MarkupString.Decoding.Decoder;
+namespace MarkupString.Ansi.Decoding;
+
+/// <summary>
+/// Pictures from the server: Kitty graphics (<c>APC G</c>, Unicode placeholders included), iTerm2 inline images
+/// (<c>OSC 1337 File=</c>, and its multipart form) and sixel (<c>DCS q</c>). Each becomes an
+/// <see cref="ImageMarkup"/> over the cells it covers, its pixels kept in the decoder's <see cref="PictureStore"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// A picture is placed as a terminal places it: its first row beside the text already on the line, each further
+/// row on a line of its own. A picture drawn between a cursor save and restore (<c>ESC 7</c> … <c>ESC 8</c>) is
+/// drawn over the lines that follow it instead, which is how a game writes a picture beside text.
+/// </para>
+/// <para>
+/// Only pictures sent in the sequence itself are read (Kitty <c>t=d</c>): one that names a file, a temporary file
+/// or shared memory is refused, since the server's files are not the client's.
+/// </para>
+/// </remarks>
+public sealed class PicturesPlugin : IDecoderPlugin
+{
+	/// <summary>The most base64 a chunked picture may add up to.</summary>
+	public const int MaxTransmission = 16 * 1024 * 1024;
+
+	private static readonly Dictionary<int, int> DiacriticIndex = BuildDiacriticIndex();
+
+	/// <summary>The one instance.</summary>
+	public static PicturesPlugin Instance { get; } = new();
+
+	private PicturesPlugin()
+	{
+	}
+
+	/// <inheritdoc/>
+	public string Name => "pictures";
+
+	/// <summary>The pictures <paramref name="decoder"/> has read.</summary>
+	public static PictureStore Pictures(Decoder decoder)
+	{
+		ArgumentNullException.ThrowIfNull(decoder);
+		return decoder.State<PictureState>().Store;
+	}
+
+	/// <inheritdoc/>
+	public void Register(DecoderBuilder builder)
+	{
+		ArgumentNullException.ThrowIfNull(builder);
+		builder
+			.OnApc(static (payload, context) => payload.Length > 0 && payload[0] == 'G' && Kitty(payload[1..], context))
+			.OnOsc(1337, static (payload, context) => InlineImage(payload, context))
+			.OnDcs('q', static (in CsiSequence header, ReadOnlySpan<char> data, DecodeContext context) => Sixel(header, data, context))
+			.OnPrint(static (text, context) => Placeholders(text, context))
+			.OnLineEnd(static context => DrawOverlays(context));
+	}
+
+	// ── Kitty ───────────────────────────────────────────────────────────────────
+
+	private static bool Kitty(ReadOnlySpan<char> payload, DecodeContext context)
+	{
+		var state = context.State<PictureState>();
+		var separator = payload.IndexOf(';');
+		var control = separator < 0 ? payload : payload[..separator];
+		var data = separator < 0 ? [] : payload[(separator + 1)..];
+		var keys = KittyKeys.Parse(control);
+
+		if (state.Chunks is { } chunks)
+		{
+			// A continuation: only m (and q) count; the keys came with the first chunk.
+			if (chunks.Length + data.Length > MaxTransmission)
+			{
+				state.Chunks = null;
+				context.Diagnostics.PicturesFailed++;
+				return true;
+			}
+
+			chunks.Append(data);
+			if (keys.More) return true;
+			state.Chunks = null;
+			Complete(state.ChunkKeys, chunks.ToString(), context);
+			return true;
+		}
+
+		if (keys.More)
+		{
+			state.Chunks = new StringBuilder().Append(data);
+			state.ChunkKeys = keys;
+			return true;
+		}
+
+		Complete(keys, data.ToString(), context);
+		return true;
+	}
+
+	private static void Complete(KittyKeys keys, string base64, DecodeContext context)
+	{
+		var state = context.State<PictureState>();
+		switch (keys.Action)
+		{
+			case 'd':
+				Delete(keys, state);
+				return;
+			case 'p':
+				if (state.KittyImages.TryGetValue(keys.Id, out var known) && state.Store.TryGet(known.Key, out var stored))
+				{
+					var columns = keys.Columns > 0 ? keys.Columns : known.Columns;
+					var rows = keys.Rows > 0 ? keys.Rows : known.Rows;
+					Place(context, stored, columns, rows, cursorRight: true, keys.StayPut);
+					KittyReply(context, keys, null);
+				}
+				else
+				{
+					KittyReply(context, keys, "ENOENT:no such image");
+				}
+
+				return;
+			case 't' or 'T' or 'q':
+				break;
+			default:
+				// Animation (a=f, a=a, a=c): a moving picture is read as its first frame.
+				return;
+		}
+
+		if (keys.Medium != 'd')
+		{
+			context.Diagnostics.PicturesFailed++;
+			KittyReply(context, keys, "EINVAL:only direct transmission is read");
+			return;
+		}
+
+		var bytes = FromBase64(base64);
+		if (bytes is not null && keys.Compression == 'z') bytes = Inflate(bytes, state.Store.MaxPixels * 4 + 1024);
+		var picture = bytes is null ? null : DecodeKitty(keys, bytes, state.Store);
+		if (picture is null)
+		{
+			context.Diagnostics.PicturesFailed++;
+			KittyReply(context, keys, "EBADF:could not decode the picture");
+			return;
+		}
+
+		if (keys.Action == 'q')
+		{
+			KittyReply(context, keys, null);
+			return;
+		}
+
+		var (cellColumns, cellRows) = Cells(picture.Width, picture.Height, keys.Columns, keys.Rows, context.Identity);
+		var id = keys.Id;
+		if (id == 0 && keys.Number != 0) id = state.NextKittyId++;
+		if (id != 0) state.KittyImages[id] = new KittyImage(picture.Key, cellColumns, cellRows);
+
+		if (keys.Action == 'T' && !keys.Virtual) Place(context, picture, cellColumns, cellRows, cursorRight: true, keys.StayPut);
+		KittyReply(context, keys with { Id = id }, null);
+	}
+
+	private static StoredPicture? DecodeKitty(KittyKeys keys, byte[] bytes, PictureStore store)
+	{
+		switch (keys.Format)
+		{
+			case 100:
+				return PngDecoder.TryDecode(bytes, store.MaxPixels, out var width, out var height, out var rgba)
+					? store.Add(width, height, rgba, bytes, "image/png")
+					: null;
+			case 24 or 32:
+				{
+					if (keys.Width <= 0 || keys.Height <= 0 || (long)keys.Width * keys.Height > store.MaxPixels) return null;
+					var channels = keys.Format / 8;
+					if (bytes.Length < (long)keys.Width * keys.Height * channels) return null;
+					var pixels = new byte[keys.Width * keys.Height * 4];
+					for (var i = 0; i < keys.Width * keys.Height; i++)
+					{
+						pixels[i * 4] = bytes[i * channels];
+						pixels[i * 4 + 1] = bytes[i * channels + 1];
+						pixels[i * 4 + 2] = bytes[i * channels + 2];
+						pixels[i * 4 + 3] = channels == 4 ? bytes[i * 4 + 3] : (byte)255;
+					}
+
+					return store.Add(keys.Width, keys.Height, pixels);
+				}
+			default:
+				return null;
+		}
+	}
+
+	private static void Delete(KittyKeys keys, PictureState state)
+	{
+		switch (keys.Delete)
+		{
+			case 'a' or 'A' or '\0':
+				state.KittyImages.Clear();
+				break;
+			case 'i' or 'I':
+				state.KittyImages.Remove(keys.Id);
+				break;
+			case 'n' or 'N':
+				state.KittyImages.Remove(keys.Id);
+				break;
+		}
+	}
+
+	private static void KittyReply(DecodeContext context, KittyKeys keys, string? error)
+	{
+		if (keys.Id == 0 && keys.Number == 0) return;
+		if (keys.Quiet >= 2 || (error is null && keys.Quiet >= 1)) return;
+		if ((context.Identity.Answers & ClientAnswers.Pictures) == 0) return;
+
+		var reply = new StringBuilder("\e_G");
+		if (keys.Id != 0) reply.Append(CultureInfo.InvariantCulture, $"i={keys.Id}");
+		if (keys.Number != 0) reply.Append(keys.Id != 0 ? "," : "").Append(CultureInfo.InvariantCulture, $"I={keys.Number}");
+		reply.Append(';').Append(error ?? "OK").Append("\e\\");
+		context.Reply(reply.ToString());
+	}
+
+	private static bool Placeholders(ReadOnlySpan<char> text, DecodeContext context)
+	{
+		if (text.IndexOf('\uDBFB') < 0) return false;
+
+		var state = context.State<PictureState>();
+		var at = 0;
+		while (at < text.Length)
+		{
+			var start = IndexOfPlaceholder(text, at);
+			if (start < 0)
+			{
+				context.Write(text[at..]);
+				break;
+			}
+
+			if (start > at) context.Write(text[at..start]);
+
+			// One stretch of placeholders on the same row, in consecutive columns, is one write.
+			var id = PlaceholderId(context);
+			int row = -1, column = -1, count = 0, first = 0;
+			var i = start;
+			while (i < text.Length && IsPlaceholderAt(text, i))
+			{
+				i += 2;
+				var cellRow = Diacritic(text, ref i);
+				var cellColumn = Diacritic(text, ref i);
+				Diacritic(text, ref i);
+
+				if (cellRow < 0) cellRow = row < 0 ? 0 : row;
+				if (cellColumn < 0) cellColumn = column < 0 ? 0 : column + 1;
+				if (count > 0 && (cellRow != row || cellColumn != column + 1))
+				{
+					WritePlaceholders(context, state, id, row, first, count);
+					count = 0;
+				}
+
+				if (count == 0) first = cellColumn;
+				row = cellRow;
+				column = cellColumn;
+				count++;
+			}
+
+			WritePlaceholders(context, state, id, row, first, count);
+			at = i;
+		}
+
+		return true;
+	}
+
+	private static void WritePlaceholders(DecodeContext context, PictureState state, uint id, int row, int first, int count)
+	{
+		if (count == 0) return;
+		var blank = new string(' ', count);
+		if (state.KittyImages.TryGetValue(id, out var known) && state.Store.TryGet(known.Key, out var stored) && row < known.Rows)
+		{
+			var image = Markup(stored) with { Row = new PictureRow(row, known.Rows, known.Columns) { FirstColumn = first } };
+			context.Write(blank, image);
+		}
+		else
+		{
+			context.Write(blank);
+		}
+	}
+
+	private static uint PlaceholderId(DecodeContext context) =>
+		context.Pen(VtPens.Style) is AnsiMarkup { Style.Foreground: { } color }
+			? color switch
+			{
+				AnsiColor.Rgb rgb => (uint)(rgb.R << 16 | rgb.G << 8 | rgb.B),
+				AnsiColor.Xterm xterm => xterm.Index,
+				AnsiColor.Standard standard => (uint)(standard.Index + (standard.Bright ? 8 : 0)),
+				_ => 0u,
+			}
+			: 0u;
+
+	private static int IndexOfPlaceholder(ReadOnlySpan<char> text, int from)
+	{
+		for (var i = from; i < text.Length - 1; i++)
+		{
+			if (IsPlaceholderAt(text, i)) return i;
+		}
+
+		return -1;
+	}
+
+	private static bool IsPlaceholderAt(ReadOnlySpan<char> text, int i) => i + 1 < text.Length && text[i] == '\uDBFB' && text[i + 1] == '\uDEEE';
+
+	private static int Diacritic(ReadOnlySpan<char> text, ref int i)
+	{
+		if (i >= text.Length || Rune.DecodeFromUtf16(text[i..], out var rune, out var used) != System.Buffers.OperationStatus.Done) return -1;
+		if (!DiacriticIndex.TryGetValue(rune.Value, out var index)) return -1;
+		i += used;
+		return index;
+	}
+
+	private static Dictionary<int, int> BuildDiacriticIndex()
+	{
+		var index = new Dictionary<int, int>(TerminalPictureWriter.Diacritics.Length);
+		for (var i = 0; i < TerminalPictureWriter.Diacritics.Length; i++) index[TerminalPictureWriter.Diacritics[i]] = i;
+		return index;
+	}
+
+	// ── iTerm2 ──────────────────────────────────────────────────────────────────
+
+	private static bool InlineImage(ReadOnlySpan<char> payload, DecodeContext context)
+	{
+		var state = context.State<PictureState>();
+		if (payload.StartsWith("File=", StringComparison.Ordinal))
+		{
+			var colon = payload.IndexOf(':');
+			if (colon < 0) return false;
+			ShowInlineImage(InlineArguments.Parse(payload[5..colon]), FromBase64(payload[(colon + 1)..].ToString()), context);
+			return true;
+		}
+
+		if (payload.StartsWith("MultipartFile=", StringComparison.Ordinal))
+		{
+			state.Multipart = InlineArguments.Parse(payload[14..]);
+			state.MultipartData = new StringBuilder();
+			return true;
+		}
+
+		if (payload.StartsWith("FilePart=", StringComparison.Ordinal))
+		{
+			if (state.MultipartData is not { } parts) return true;
+			if (parts.Length + payload.Length > MaxTransmission)
+			{
+				state.Multipart = null;
+				state.MultipartData = null;
+				context.Diagnostics.PicturesFailed++;
+				return true;
+			}
+
+			parts.Append(payload[9..]);
+			return true;
+		}
+
+		if (payload.SequenceEqual("FileEnd"))
+		{
+			if (state.Multipart is { } arguments && state.MultipartData is { } data)
+			{
+				ShowInlineImage(arguments, FromBase64(data.ToString()), context);
+			}
+
+			state.Multipart = null;
+			state.MultipartData = null;
+			return true;
+		}
+
+		return false;
+	}
+
+	private static void ShowInlineImage(InlineArguments arguments, byte[]? bytes, DecodeContext context)
+	{
+		if (bytes is null)
+		{
+			context.Diagnostics.PicturesFailed++;
+			return;
+		}
+
+		if (!arguments.Inline)
+		{
+			context.Raise(new DownloadEvent(arguments.Name, bytes.Length));
+			return;
+		}
+
+		var store = context.State<PictureState>().Store;
+		StoredPicture? picture = null;
+		if (PngDecoder.TryDecode(bytes, store.MaxPixels, out var width, out var height, out var rgba))
+		{
+			picture = store.Add(width, height, rgba, bytes, "image/png");
+		}
+		else if (Sniff(bytes) is { } file && (long)file.Width * file.Height <= store.MaxPixels)
+		{
+			// Not decodable here, but a browser shows it.
+			picture = store.Add(file.Width, file.Height, null, bytes, file.MediaType);
+		}
+
+		if (picture is null)
+		{
+			context.Diagnostics.PicturesFailed++;
+			return;
+		}
+
+		var identity = context.Identity;
+		var columns = arguments.Width.ToCells(identity.Columns, identity.CellWidth);
+		var rows = arguments.Height.ToCells(identity.Rows, identity.CellHeight);
+		if (!arguments.PreserveAspectRatio && columns > 0 && rows > 0)
+		{
+			Place(context, picture, Math.Min(columns, identity.Columns), rows, cursorRight: true, stayPut: false, arguments.Name);
+			return;
+		}
+
+		var (cellColumns, cellRows) = Cells(picture.Width, picture.Height, columns, rows, identity);
+		Place(context, picture, cellColumns, cellRows, cursorRight: true, stayPut: false, arguments.Name);
+	}
+
+	/// <summary>The size and type of a GIF, JPEG or WebP, read from its header.</summary>
+	private static (int Width, int Height, string MediaType)? Sniff(ReadOnlySpan<byte> data)
+	{
+		if (data.Length >= 10 && data.StartsWith("GIF8"u8))
+		{
+			return (BinaryPrimitives.ReadUInt16LittleEndian(data[6..]), BinaryPrimitives.ReadUInt16LittleEndian(data[8..]), "image/gif");
+		}
+
+		if (data.Length >= 30 && data.StartsWith("RIFF"u8) && data[8..12].SequenceEqual("WEBP"u8))
+		{
+			var chunk = data[12..16];
+			if (chunk.SequenceEqual("VP8 "u8))
+				return (BinaryPrimitives.ReadUInt16LittleEndian(data[26..]) & 0x3FFF, BinaryPrimitives.ReadUInt16LittleEndian(data[28..]) & 0x3FFF, "image/webp");
+			if (chunk.SequenceEqual("VP8L"u8) && data.Length >= 25)
+			{
+				var bits = BinaryPrimitives.ReadUInt32LittleEndian(data[21..]);
+				return ((int)(bits & 0x3FFF) + 1, (int)((bits >> 14) & 0x3FFF) + 1, "image/webp");
+			}
+
+			if (chunk.SequenceEqual("VP8X"u8))
+				return ((data[24] | data[25] << 8 | data[26] << 16) + 1, (data[27] | data[28] << 8 | data[29] << 16) + 1, "image/webp");
+		}
+
+		if (data.Length >= 4 && data[0] == 0xFF && data[1] == 0xD8)
+		{
+			var i = 2;
+			while (i + 9 < data.Length && data[i] == 0xFF)
+			{
+				var marker = data[i + 1];
+				var length = BinaryPrimitives.ReadUInt16BigEndian(data[(i + 2)..]);
+				if (marker is >= 0xC0 and <= 0xCF and not 0xC4 and not 0xC8 and not 0xCC)
+				{
+					return (BinaryPrimitives.ReadUInt16BigEndian(data[(i + 7)..]), BinaryPrimitives.ReadUInt16BigEndian(data[(i + 5)..]), "image/jpeg");
+				}
+
+				i += 2 + length;
+			}
+		}
+
+		return null;
+	}
+
+	// ── Sixel ───────────────────────────────────────────────────────────────────
+
+	private static bool Sixel(in CsiSequence header, ReadOnlySpan<char> data, DecodeContext context)
+	{
+		var store = context.State<PictureState>().Store;
+		if (!SixelDecoder.TryDecode(data, header.Get(1) == 1, store.MaxPixels, out var width, out var height, out var rgba))
+		{
+			context.Diagnostics.PicturesFailed++;
+			return true;
+		}
+
+		var picture = store.Add(width, height, rgba);
+		var (columns, rows) = Cells(width, height, 0, 0, context.Identity);
+		Place(context, picture, columns, rows, cursorRight: false, stayPut: false);
+		return true;
+	}
+
+	// ── Placing ─────────────────────────────────────────────────────────────────
+
+	/// <summary>The cells a picture takes: as asked, else its pixels over the cell size, no wider than the pane.</summary>
+	private static (int Columns, int Rows) Cells(int width, int height, int columns, int rows, ClientIdentity identity)
+	{
+		var cellWidth = Math.Max(1, identity.CellWidth);
+		var cellHeight = Math.Max(1, identity.CellHeight);
+		if (columns <= 0 && rows <= 0)
+		{
+			columns = (width + cellWidth - 1) / cellWidth;
+			rows = (height + cellHeight - 1) / cellHeight;
+		}
+		else if (rows <= 0)
+		{
+			rows = (int)Math.Ceiling((double)columns * cellWidth * height / width / cellHeight);
+		}
+		else if (columns <= 0)
+		{
+			columns = (int)Math.Ceiling((double)rows * cellHeight * width / height / cellWidth);
+		}
+
+		if (identity.Columns > 0 && columns > identity.Columns)
+		{
+			rows = Math.Max(1, (int)Math.Ceiling((double)rows * identity.Columns / columns));
+			columns = identity.Columns;
+		}
+
+		return (Math.Max(1, columns), Math.Max(1, rows));
+	}
+
+	private static ImageMarkup Markup(StoredPicture picture, string? description = null) =>
+		new(picture.Source, description, picture.Width, picture.Height);
+
+	private static void Place(DecodeContext context, StoredPicture picture, int columns, int rows, bool cursorRight, bool stayPut, string? description = null)
+	{
+		var image = Markup(picture, description);
+		var vt = context.State<VtState>();
+		if (vt.SavedColumn is not null || stayPut)
+		{
+			// Drawn over the lines that follow, which the server leaves room for.
+			context.State<PictureState>().Overlays.Add(new Overlay(image, rows, columns, context.Column));
+			return;
+		}
+
+		context.PlacePicture(image, rows, columns, cursorRight);
+	}
+
+	private static void DrawOverlays(DecodeContext context)
+	{
+		var overlays = context.State<PictureState>().Overlays;
+		if (overlays.Count == 0) return;
+
+		var cursor = context.Column;
+		for (var i = 0; i < overlays.Count; i++)
+		{
+			var overlay = overlays[i];
+			context.MoveToColumn(overlay.Column);
+			context.Write(new string(' ', overlay.Columns), overlay.Image with { Row = new PictureRow(overlay.Next, overlay.Rows, overlay.Columns) });
+			overlay.Next++;
+		}
+
+		overlays.RemoveAll(overlay => overlay.Next >= overlay.Rows);
+		context.MoveToColumn(cursor);
+	}
+
+	// ── Helpers ─────────────────────────────────────────────────────────────────
+
+	private static byte[]? FromBase64(string base64)
+	{
+		try
+		{
+			return Convert.FromBase64String(base64);
+		}
+		catch (FormatException)
+		{
+			return null;
+		}
+	}
+
+	private static byte[]? Inflate(byte[] data, long limit)
+	{
+		try
+		{
+			using var input = new MemoryStream(data);
+			using var inflater = new ZLibStream(input, CompressionMode.Decompress);
+			using var output = new MemoryStream();
+			var buffer = new byte[81920];
+			int read;
+			while ((read = inflater.Read(buffer, 0, buffer.Length)) > 0)
+			{
+				output.Write(buffer, 0, read);
+				if (output.Length > limit) return null;
+			}
+
+			return output.ToArray();
+		}
+		catch (InvalidDataException)
+		{
+			return null;
+		}
+	}
+
+	internal readonly record struct KittyImage(string Key, int Columns, int Rows);
+
+	internal sealed class Overlay(ImageMarkup image, int rows, int columns, int column)
+	{
+		public ImageMarkup Image { get; } = image;
+
+		public int Rows { get; } = rows;
+
+		public int Columns { get; } = columns;
+
+		public int Column { get; } = column;
+
+		public int Next { get; set; }
+	}
+
+	internal readonly record struct KittyKeys
+	{
+		public char Action { get; init; }
+
+		public char Medium { get; init; }
+
+		public char Compression { get; init; }
+
+		public char Delete { get; init; }
+
+		public int Format { get; init; }
+
+		public uint Id { get; init; }
+
+		public uint Number { get; init; }
+
+		public int Width { get; init; }
+
+		public int Height { get; init; }
+
+		public int Columns { get; init; }
+
+		public int Rows { get; init; }
+
+		public int Quiet { get; init; }
+
+		public bool More { get; init; }
+
+		public bool Virtual { get; init; }
+
+		public bool StayPut { get; init; }
+
+		public static KittyKeys Parse(ReadOnlySpan<char> control)
+		{
+			var keys = new KittyKeys { Action = 't', Medium = 'd', Format = 32 };
+			foreach (var range in control.Split(','))
+			{
+				var pair = control[range];
+				if (pair.Length < 3 || pair[1] != '=') continue;
+				var value = pair[2..];
+				int.TryParse(value, NumberStyles.AllowLeadingSign, CultureInfo.InvariantCulture, out var number);
+				keys = pair[0] switch
+				{
+					'a' => keys with { Action = value[0] },
+					't' => keys with { Medium = value[0] },
+					'o' => keys with { Compression = value[0] },
+					'd' => keys with { Delete = value[0] },
+					'f' => keys with { Format = number },
+					'i' => keys with { Id = (uint)Math.Max(0, number) },
+					'I' => keys with { Number = (uint)Math.Max(0, number) },
+					's' => keys with { Width = number },
+					'v' => keys with { Height = number },
+					'c' => keys with { Columns = number },
+					'r' => keys with { Rows = number },
+					'q' => keys with { Quiet = number },
+					'm' => keys with { More = number == 1 },
+					'U' => keys with { Virtual = number == 1 },
+					'C' => keys with { StayPut = number == 1 },
+					_ => keys,
+				};
+			}
+
+			return keys;
+		}
+	}
+
+	internal readonly record struct InlineSize(int Value, char Unit)
+	{
+		public static InlineSize Auto => default;
+
+		public int ToCells(int paneCells, int cellPixels) => Unit switch
+		{
+			'c' => Value,
+			'p' => (Value + cellPixels - 1) / Math.Max(1, cellPixels),
+			'%' => Math.Max(1, paneCells * Value / 100),
+			_ => 0,
+		};
+
+		public static InlineSize Parse(ReadOnlySpan<char> text)
+		{
+			if (text.IsEmpty || text.SequenceEqual("auto")) return Auto;
+			var unit = 'c';
+			if (text.EndsWith("px", StringComparison.Ordinal))
+			{
+				unit = 'p';
+				text = text[..^2];
+			}
+			else if (text.EndsWith("%", StringComparison.Ordinal))
+			{
+				unit = '%';
+				text = text[..^1];
+			}
+
+			return int.TryParse(text, NumberStyles.None, CultureInfo.InvariantCulture, out var value) && value > 0 ? new InlineSize(value, unit) : Auto;
+		}
+	}
+
+	internal sealed record InlineArguments(string? Name, bool Inline, InlineSize Width, InlineSize Height, bool PreserveAspectRatio)
+	{
+		public static InlineArguments Parse(ReadOnlySpan<char> text)
+		{
+			string? name = null;
+			var inline = false;
+			InlineSize width = default, height = default;
+			var preserve = true;
+			foreach (var range in text.Split(';'))
+			{
+				var pair = text[range];
+				var equals = pair.IndexOf('=');
+				if (equals < 0) continue;
+				var key = pair[..equals];
+				var value = pair[(equals + 1)..];
+				if (key.SequenceEqual("name"))
+				{
+					var bytes = FromBase64(value.ToString());
+					name = bytes is null ? null : Encoding.UTF8.GetString(bytes);
+				}
+				else if (key.SequenceEqual("inline")) inline = value.SequenceEqual("1");
+				else if (key.SequenceEqual("width")) width = InlineSize.Parse(value);
+				else if (key.SequenceEqual("height")) height = InlineSize.Parse(value);
+				else if (key.SequenceEqual("preserveAspectRatio")) preserve = !value.SequenceEqual("0");
+			}
+
+			return new InlineArguments(name, inline, width, height, preserve);
+		}
+	}
+}
+
+/// <summary>The pictures plugin's state for one decoder.</summary>
+internal sealed class PictureState
+{
+	public PictureStore Store { get; } = new();
+
+	public Dictionary<uint, PicturesPlugin.KittyImage> KittyImages { get; } = [];
+
+	public uint NextKittyId { get; set; } = 0x7F000000;
+
+	public StringBuilder? Chunks { get; set; }
+
+	public PicturesPlugin.KittyKeys ChunkKeys { get; set; }
+
+	public PicturesPlugin.InlineArguments? Multipart { get; set; }
+
+	public StringBuilder? MultipartData { get; set; }
+
+	public List<PicturesPlugin.Overlay> Overlays { get; } = [];
+}
+
+/// <summary>Registers the pictures plugin.</summary>
+public static class PictureDecoding
+{
+	/// <summary>The registry with <see cref="PicturesPlugin"/>.</summary>
+	public static DecoderRegistry WithPictures(this DecoderRegistry registry)
+	{
+		ArgumentNullException.ThrowIfNull(registry);
+		return registry.With(PicturesPlugin.Instance);
+	}
+
+	/// <summary>The pictures <paramref name="decoder"/> has read.</summary>
+	public static PictureStore Pictures(this Decoder decoder) => PicturesPlugin.Pictures(decoder);
+}
diff --git a/MarkupString.Ansi/Decoding/PngDecoder.cs b/MarkupString.Ansi/Decoding/PngDecoder.cs
new file mode 100644
index 0000000..2a58ddb
--- /dev/null
+++ b/MarkupString.Ansi/Decoding/PngDecoder.cs
@@ -0,0 +1,260 @@
+using System.Buffers.Binary;
+using System.IO.Compression;
+namespace MarkupString.Ansi.Decoding;
+
+/// <summary>
+/// Decodes a PNG to RGBA: every colour type and bit depth, transparency (<c>tRNS</c>) and Adam7 interlacing.
+/// Ancillary chunks other than <c>tRNS</c> are skipped, gamma included.
+/// </summary>
+internal static class PngDecoder
+{
+	private static ReadOnlySpan<byte> Signature => [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A];
+
+	// Adam7: start column, start row, column step, row step.
+	private static readonly (int X, int Y, int Dx, int Dy)[] Passes =
+	[
+		(0, 0, 8, 8), (4, 0, 8, 8), (0, 4, 4, 8), (2, 0, 4, 4), (0, 2, 2, 4), (1, 0, 2, 2), (0, 1, 1, 2),
+	];
+
+	/// <summary>Whether <paramref name="data"/> starts like a PNG.</summary>
+	public static bool IsPng(ReadOnlySpan<byte> data) => data.StartsWith(Signature);
+
+	/// <summary>Reads the size from the header alone.</summary>
+	public static bool TryReadSize(ReadOnlySpan<byte> data, out int width, out int height)
+	{
+		width = height = 0;
+		if (data.Length < 24 || !IsPng(data)) return false;
+		width = BinaryPrimitives.ReadInt32BigEndian(data[16..]);
+		height = BinaryPrimitives.ReadInt32BigEndian(data[20..]);
+		return width > 0 && height > 0;
+	}
+
+	/// <summary>Decodes <paramref name="data"/>, refusing a picture of more than <paramref name="maxPixels"/>.</summary>
+	public static bool TryDecode(ReadOnlySpan<byte> data, long maxPixels, out int width, out int height, out byte[] rgba)
+	{
+		width = height = 0;
+		rgba = [];
+		try
+		{
+			return Decode(data, maxPixels, out width, out height, out rgba);
+		}
+		catch (InvalidDataException)
+		{
+			return false;
+		}
+	}
+
+	private static bool Decode(ReadOnlySpan<byte> data, long maxPixels, out int width, out int height, out byte[] rgba)
+	{
+		width = height = 0;
+		rgba = [];
+		if (!IsPng(data)) return false;
+
+		var offset = Signature.Length;
+		int depth = 0, colorType = -1, interlace = 0;
+		byte[]? palette = null;
+		byte[]? transparency = null;
+		using var compressed = new MemoryStream();
+
+		while (offset + 8 <= data.Length)
+		{
+			var length = BinaryPrimitives.ReadInt32BigEndian(data[offset..]);
+			if (length < 0 || offset + 12L + length > data.Length) return false;
+			var type = data.Slice(offset + 4, 4);
+			var body = data.Slice(offset + 8, length);
+			offset += 12 + length;
+
+			if (type.SequenceEqual("IHDR"u8))
+			{
+				if (length < 13) return false;
+				width = BinaryPrimitives.ReadInt32BigEndian(body);
+				height = BinaryPrimitives.ReadInt32BigEndian(body[4..]);
+				depth = body[8];
+				colorType = body[9];
+				interlace = body[12];
+				if (width <= 0 || height <= 0 || (long)width * height > maxPixels) return false;
+				if (body[10] != 0 || body[11] != 0 || interlace > 1) return false;
+				if (!Valid(colorType, depth)) return false;
+			}
+			else if (type.SequenceEqual("PLTE"u8))
+			{
+				palette = body.ToArray();
+			}
+			else if (type.SequenceEqual("tRNS"u8))
+			{
+				transparency = body.ToArray();
+			}
+			else if (type.SequenceEqual("IDAT"u8))
+			{
+				compressed.Write(body);
+			}
+			else if (type.SequenceEqual("IEND"u8))
+			{
+				break;
+			}
+		}
+
+		if (colorType < 0 || (colorType == 3 && palette is null)) return false;
+
+		compressed.Position = 0;
+		using var inflater = new ZLibStream(compressed, CompressionMode.Decompress);
+		var channels = colorType switch { 0 => 1, 2 => 3, 3 => 1, 4 => 2, _ => 4 };
+		var bitsPerPixel = channels * depth;
+		var pixelBytes = Math.Max(1, bitsPerPixel / 8);
+
+		var expected = 0L;
+		foreach (var (x, y, dx, dy) in interlace == 1 ? Passes : [(0, 0, 1, 1)])
+		{
+			var columns = (width - x + dx - 1) / dx;
+			var rows = (height - y + dy - 1) / dy;
+			if (columns > 0 && rows > 0) expected += rows * (1 + ((long)columns * bitsPerPixel + 7) / 8);
+		}
+
+		if (expected > int.MaxValue) return false;
+		var raw = new byte[expected];
+		var read = 0;
+		while (read < raw.Length)
+		{
+			var n = inflater.Read(raw, read, raw.Length - read);
+			if (n == 0) return false;
+			read += n;
+		}
+
+		rgba = new byte[(long)width * height * 4];
+		var at = 0;
+		foreach (var (x0, y0, dx, dy) in interlace == 1 ? Passes : [(0, 0, 1, 1)])
+		{
+			var columns = (width - x0 + dx - 1) / dx;
+			var rows = (height - y0 + dy - 1) / dy;
+			if (columns <= 0 || rows <= 0) continue;
+
+			var stride = (int)(((long)columns * bitsPerPixel + 7) / 8);
+			var previous = new byte[stride];
+			var current = new byte[stride];
+			for (var row = 0; row < rows; row++)
+			{
+				var filter = raw[at];
+				raw.AsSpan(at + 1, stride).CopyTo(current);
+				at += 1 + stride;
+				if (!Unfilter(filter, current, previous, pixelBytes)) return false;
+
+				var y = y0 + row * dy;
+				for (var column = 0; column < columns; column++)
+				{
+					var x = x0 + column * dx;
+					Pixel(current, column, colorType, depth, palette, transparency, rgba.AsSpan((y * width + x) * 4, 4));
+				}
+
+				(previous, current) = (current, previous);
+			}
+		}
+
+		return true;
+	}
+
+	private static bool Valid(int colorType, int depth) => colorType switch
+	{
+		0 => depth is 1 or 2 or 4 or 8 or 16,
+		3 => depth is 1 or 2 or 4 or 8,
+		2 or 4 or 6 => depth is 8 or 16,
+		_ => false,
+	};
+
+	private static bool Unfilter(byte filter, Span<byte> line, ReadOnlySpan<byte> previous, int bpp)
+	{
+		switch (filter)
+		{
+			case 0:
+				return true;
+			case 1:
+				for (var i = bpp; i < line.Length; i++) line[i] += line[i - bpp];
+				return true;
+			case 2:
+				for (var i = 0; i < line.Length; i++) line[i] += previous[i];
+				return true;
+			case 3:
+				for (var i = 0; i < line.Length; i++)
+				{
+					var left = i >= bpp ? line[i - bpp] : 0;
+					line[i] += (byte)((left + previous[i]) >> 1);
+				}
+
+				return true;
+			case 4:
+				for (var i = 0; i < line.Length; i++)
+				{
+					int a = i >= bpp ? line[i - bpp] : 0, b = previous[i], c = i >= bpp ? previous[i - bpp] : 0;
+					int p = a + b - c, pa = Math.Abs(p - a), pb = Math.Abs(p - b), pc = Math.Abs(p - c);
+					line[i] += (byte)(pa <= pb && pa <= pc ? a : pb <= pc ? b : c);
+				}
+
+				return true;
+			default:
+				return false;
+		}
+	}
+
+	private static void Pixel(ReadOnlySpan<byte> line, int column, int colorType, int depth, byte[]? palette, byte[]? transparency, Span<byte> output)
+	{
+		switch (colorType)
+		{
+			case 0:
+				{
+					var value = Sample(line, column, depth);
+					var gray = Scale(value, depth);
+					output[0] = output[1] = output[2] = gray;
+					output[3] = transparency is { Length: >= 2 } && BinaryPrimitives.ReadUInt16BigEndian(transparency) == value ? (byte)0 : (byte)255;
+					break;
+				}
+			case 2:
+				{
+					int r = Sample(line, column * 3, depth), g = Sample(line, column * 3 + 1, depth), b = Sample(line, column * 3 + 2, depth);
+					output[0] = Scale(r, depth);
+					output[1] = Scale(g, depth);
+					output[2] = Scale(b, depth);
+					output[3] = transparency is { Length: >= 6 }
+						&& BinaryPrimitives.ReadUInt16BigEndian(transparency) == r
+						&& BinaryPrimitives.ReadUInt16BigEndian(transparency.AsSpan(2)) == g
+						&& BinaryPrimitives.ReadUInt16BigEndian(transparency.AsSpan(4)) == b
+							? (byte)0
+							: (byte)255;
+					break;
+				}
+			case 3:
+				{
+					var index = Sample(line, column, depth);
+					if (index * 3 + 2 < palette!.Length)
+					{
+						output[0] = palette[index * 3];
+						output[1] = palette[index * 3 + 1];
+						output[2] = palette[index * 3 + 2];
+					}
+
+					output[3] = transparency is not null && index < transparency.Length ? transparency[index] : (byte)255;
+					break;
+				}
+			case 4:
+				output[0] = output[1] = output[2] = Scale(Sample(line, column * 2, depth), depth);
+				output[3] = Scale(Sample(line, column * 2 + 1, depth), depth);
+				break;
+			default:
+				for (var i = 0; i < 4; i++) output[i] = Scale(Sample(line, column * 4 + i, depth), depth);
+				break;
+		}
+	}
+
+	/// <summary>Sample <paramref name="index"/> of a line, at its depth.</summary>
+	private static int Sample(ReadOnlySpan<byte> line, int index, int depth) => depth switch
+	{
+		16 => BinaryPrimitives.ReadUInt16BigEndian(line[(index * 2)..]),
+		8 => line[index],
+		_ => (line[index * depth / 8] >> (8 - depth - index * depth % 8)) & ((1 << depth) - 1),
+	};
+
+	private static byte Scale(int value, int depth) => depth switch
+	{
+		16 => (byte)(value >> 8),
+		8 => (byte)value,
+		_ => (byte)(value * 255 / ((1 << depth) - 1)),
+	};
+}
diff --git a/MarkupString.Ansi/Decoding/SixelDecoder.cs b/MarkupString.Ansi/Decoding/SixelDecoder.cs
new file mode 100644
index 0000000..6b7c7df
--- /dev/null
+++ b/MarkupString.Ansi/Decoding/SixelDecoder.cs
@@ -0,0 +1,246 @@
+namespace MarkupString.Ansi.Decoding;
+
+/// <summary>Decodes sixel data (the part of <c>DCS … q … ST</c> after the <c>q</c>) to RGBA.</summary>
+internal static class SixelDecoder
+{
+	// The VT340's sixteen colours, in percent.
+	private static readonly (int R, int G, int B)[] Vt340 =
+	[
+		(0, 0, 0), (20, 20, 80), (80, 13, 13), (20, 80, 20), (80, 20, 80), (20, 80, 80), (80, 80, 20), (53, 53, 53),
+		(26, 26, 26), (33, 33, 60), (60, 26, 26), (33, 60, 33), (60, 33, 60), (33, 60, 60), (60, 60, 33), (80, 80, 80),
+	];
+
+	/// <summary>Decodes <paramref name="data"/>.</summary>
+	/// <param name="data">The sixel data.</param>
+	/// <param name="transparent">Whether pixels no sixel sets are transparent (P2 = 1) rather than colour 0.</param>
+	/// <param name="maxPixels">The largest picture taken.</param>
+	/// <param name="width">Its width.</param>
+	/// <param name="height">Its height.</param>
+	/// <param name="rgba">Its pixels.</param>
+	public static bool TryDecode(ReadOnlySpan<char> data, bool transparent, long maxPixels, out int width, out int height, out byte[] rgba)
+	{
+		width = height = 0;
+		rgba = [];
+
+		var palette = new uint[256];
+		for (var i = 0; i < palette.Length; i++)
+		{
+			var (r, g, b) = Vt340[i % Vt340.Length];
+			palette[i] = Pack(Percent(r), Percent(g), Percent(b));
+		}
+
+		var canvas = new Canvas(maxPixels);
+		var color = palette[0];
+		int x = 0, band = 0;
+		var i0 = 0;
+
+		while (i0 < data.Length)
+		{
+			var c = data[i0++];
+			switch (c)
+			{
+				case '"':
+					{
+						// Raster attributes: aspect numerator and denominator, then width and height.
+						var values = Numbers(data, ref i0, 4);
+						if (values.Count >= 4 && values[2] > 0 && values[3] > 0)
+						{
+							if (!canvas.Reserve(values[2], values[3])) return false;
+						}
+
+						break;
+					}
+				case '#':
+					{
+						var values = Numbers(data, ref i0, 5);
+						if (values.Count == 0) break;
+						var register = Math.Clamp(values[0], 0, 255);
+						if (values.Count >= 5)
+						{
+							palette[register] = values[1] == 1
+								? Hls(values[2], values[3], values[4])
+								: Pack(Percent(values[2]), Percent(values[3]), Percent(values[4]));
+						}
+
+						color = palette[register];
+						break;
+					}
+				case '!':
+					{
+						var values = Numbers(data, ref i0, 1);
+						var count = values.Count > 0 ? Math.Max(1, values[0]) : 1;
+						if (i0 < data.Length && data[i0] is >= '?' and <= '~')
+						{
+							if (!canvas.Put(x, band, data[i0] - '?', count, color)) return false;
+							x += count;
+							i0++;
+						}
+
+						break;
+					}
+				case '$':
+					x = 0;
+					break;
+				case '-':
+					x = 0;
+					band++;
+					break;
+				case >= '?' and <= '~':
+					if (!canvas.Put(x, band, c - '?', 1, color)) return false;
+					x++;
+					break;
+			}
+		}
+
+		if (canvas.Width == 0 || canvas.Height == 0) return false;
+		width = canvas.Width;
+		height = canvas.Height;
+		rgba = canvas.ToRgba(transparent ? 0u : palette[0] | 0xFF000000u);
+		return true;
+	}
+
+	private static List<int> Numbers(ReadOnlySpan<char> data, ref int i, int max)
+	{
+		var values = new List<int>(max);
+		var value = 0;
+		var any = false;
+		while (i < data.Length)
+		{
+			var c = data[i];
+			if (c is >= '0' and <= '9')
+			{
+				value = Math.Min(value * 10 + (c - '0'), 1 << 20);
+				any = true;
+			}
+			else if (c == ';')
+			{
+				values.Add(value);
+				value = 0;
+				any = false;
+			}
+			else
+			{
+				break;
+			}
+
+			i++;
+		}
+
+		if (any || values.Count > 0) values.Add(value);
+		return values;
+	}
+
+	private static byte Percent(int value) => (byte)Math.Round(Math.Clamp(value, 0, 100) * 255 / 100.0);
+
+	private static uint Pack(byte r, byte g, byte b) => 0xFF000000u | ((uint)b << 16) | ((uint)g << 8) | r;
+
+	/// <summary>A sixel HLS colour: hue in degrees with blue at 0, lightness and saturation in percent.</summary>
+	private static uint Hls(int hue, int lightness, int saturation)
+	{
+		var h = ((hue + 240) % 360) / 360.0;
+		double l = Math.Clamp(lightness, 0, 100) / 100.0, s = Math.Clamp(saturation, 0, 100) / 100.0;
+		if (s == 0) return Pack((byte)(l * 255), (byte)(l * 255), (byte)(l * 255));
+		var q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+		var p = 2 * l - q;
+		return Pack(Channel(p, q, h + 1 / 3.0), Channel(p, q, h), Channel(p, q, h - 1 / 3.0));
+	}
+
+	private static byte Channel(double p, double q, double t)
+	{
+		if (t < 0) t += 1;
+		if (t > 1) t -= 1;
+		var v = t < 1 / 6.0 ? p + (q - p) * 6 * t : t < 0.5 ? q : t < 2 / 3.0 ? p + (q - p) * (2 / 3.0 - t) * 6 : p;
+		return (byte)Math.Round(v * 255);
+	}
+
+	private sealed class Canvas(long maxPixels)
+	{
+		private uint[] _pixels = [];
+		private int _stride;
+		private int _rows;
+
+		public int Width { get; private set; }
+
+		public int Height { get; private set; }
+
+		public bool Reserve(int width, int height)
+		{
+			if (!Grow(width, height)) return false;
+			Width = Math.Max(Width, width);
+			Height = Math.Max(Height, height);
+			return true;
+		}
+
+		public bool Put(int x, int band, int bits, int count, uint color)
+		{
+			if (bits == 0)
+			{
+				// Nothing drawn, but the picture is at least this wide.
+				return Extend(x + count, band * 6 + 1);
+			}
+
+			var top = band * 6;
+			if (!Extend(x + count, top + 6)) return false;
+			for (var bit = 0; bit < 6; bit++)
+			{
+				if ((bits & (1 << bit)) == 0) continue;
+				var y = top + bit;
+				Height = Math.Max(Height, y + 1);
+				_pixels.AsSpan(y * _stride + x, count).Fill(color);
+			}
+
+			return true;
+		}
+
+		public byte[] ToRgba(uint background)
+		{
+			var rgba = new byte[(long)Width * Height * 4];
+			var output = System.Runtime.InteropServices.MemoryMarshal.Cast<byte, uint>(rgba.AsSpan());
+			for (var y = 0; y < Height; y++)
+			{
+				for (var x = 0; x < Width; x++)
+				{
+					var pixel = _pixels[y * _stride + x];
+					output[y * Width + x] = pixel == 0 ? background : pixel;
+				}
+			}
+
+			if (!BitConverter.IsLittleEndian)
+			{
+				for (var i = 0; i < output.Length; i++) output[i] = System.Buffers.Binary.BinaryPrimitives.ReverseEndianness(output[i]);
+			}
+
+			return rgba;
+		}
+
+		private bool Extend(int width, int height)
+		{
+			if (!Grow(width, height)) return false;
+			Width = Math.Max(Width, width);
+			return true;
+		}
+
+		private bool Grow(int width, int height)
+		{
+			if ((long)width * height > maxPixels) return false;
+			if (width <= _stride && height <= _rows) return true;
+
+			var stride = Math.Max(_stride, width);
+			var rows = Math.Max(_rows, height);
+			if (width > _stride) stride = (int)Math.Min(Math.Max(stride, _stride * 2L), Math.Max(width, maxPixels / Math.Max(1, rows)));
+			if (height > _rows) rows = (int)Math.Min(Math.Max(rows, _rows * 2L), Math.Max(height, maxPixels / Math.Max(1, stride)));
+			if ((long)stride * rows > maxPixels)
+			{
+				stride = width > _stride ? width : _stride;
+				rows = height > _rows ? height : _rows;
+			}
+
+			var pixels = new uint[(long)stride * rows];
+			for (var y = 0; y < _rows; y++) _pixels.AsSpan(y * _stride, _stride).CopyTo(pixels.AsSpan(y * stride));
+			_pixels = pixels;
+			_stride = stride;
+			_rows = rows;
+			return true;
+		}
+	}
+}
diff --git a/MarkupString.Ansi/Decoding/VtPlugins.cs b/MarkupString.Ansi/Decoding/VtPlugins.cs
index 4766333..3bb4a80 100644
--- a/MarkupString.Ansi/Decoding/VtPlugins.cs
+++ b/MarkupString.Ansi/Decoding/VtPlugins.cs
@@ -166,8 +166,10 @@ public static AnsiStyle Apply(AnsiStyle style, in CsiSequence sequence)
 }
 
 /// <summary>
-/// The C0 controls and line editing: bell, carriage return, backspace, tab, form feed, and <c>CSI K</c>,
-/// <c>CSI J</c>, <c>CSI G</c>, <c>CSI C</c> and <c>CSI D</c>.
+/// The C0 controls and line editing: bell, carriage return, backspace, tab, form feed, vertical tab, <c>CSI K</c>,
+/// <c>CSI J</c>, <c>CSI G</c>, <c>CSI C</c>, <c>CSI D</c>, and saving and restoring the cursor's column
+/// (<c>ESC 7</c>, <c>ESC 8</c>). Cursor up (<c>CSI A</c>), index and reverse index (<c>ESC D</c>, <c>ESC M</c>)
+/// are taken and ignored.
 /// </summary>
 public sealed class ControlsPlugin : IDecoderPlugin
 {
@@ -256,6 +258,24 @@ public void Register(DecoderBuilder builder)
 			{
 				context.Backspace(Math.Max(1, sequence.Get(0, 1)));
 				return true;
+			})
+			// A scrolling pane cannot go back up a line, nor down one without ending it: cursor up, index and
+			// reverse index are taken and do nothing. A picture drawn over the cells after them is placed by the
+			// pictures plugin instead.
+			.OnCsi('A', static (in CsiSequence _, DecodeContext _) => true)
+			.OnEsc('D', static (in EscSequence _, DecodeContext _) => true)
+			.OnEsc('M', static (in EscSequence _, DecodeContext _) => true)
+			.OnEsc('7', static (in EscSequence _, DecodeContext context) =>
+			{
+				context.State<VtState>().SavedColumn = context.Column;
+				return true;
+			})
+			.OnEsc('8', static (in EscSequence _, DecodeContext context) =>
+			{
+				var state = context.State<VtState>();
+				if (state.SavedColumn is { } column) context.MoveToColumn(column);
+				state.SavedColumn = null;
+				return true;
 			});
 	}
 }
@@ -617,4 +637,6 @@ internal sealed class VtState
 	public bool G1Graphics { get; set; }
 
 	public bool ShiftedOut { get; set; }
+
+	public int? SavedColumn { get; set; }
 }
diff --git a/MarkupString.Ansi/Emitters/TerminalPictureWriter.cs b/MarkupString.Ansi/Emitters/TerminalPictureWriter.cs
index 19f5795..959f1d0 100644
--- a/MarkupString.Ansi/Emitters/TerminalPictureWriter.cs
+++ b/MarkupString.Ansi/Emitters/TerminalPictureWriter.cs
@@ -17,7 +17,7 @@ internal static class TerminalPictureWriter
 	private const string StringTerminator = "\e\\";
 
 	/// <summary>Kitty's placeholder character.</summary>
-	private const int Placeholder = 0x10EEEE;
+	internal const int Placeholder = 0x10EEEE;
 
 	/// <summary>Kitty's base64 chunk ceiling.</summary>
 	private const int KittyChunk = 4096;
@@ -26,7 +26,7 @@ internal static class TerminalPictureWriter
 	/// The diacritics Kitty reads as a row or column number, in order: the first is 0. From kitty's
 	/// <c>gen/rowcolumn-diacritics.txt</c>; a picture larger than this many cells either way is not drawn.
 	/// </summary>
-	private static readonly int[] Diacritics =
+	internal static readonly int[] Diacritics =
 	[
 		0x0305, 0x030D, 0x030E, 0x0310, 0x0312, 0x033D, 0x033E, 0x033F, 0x0346, 0x034A, 0x034B, 0x034C,
 		0x0350, 0x0351, 0x0352, 0x0357, 0x035B, 0x0363, 0x0364, 0x0365, 0x0366, 0x0367, 0x0368, 0x0369,
diff --git a/MarkupString.Ansi/PublicAPI.Unshipped.txt b/MarkupString.Ansi/PublicAPI.Unshipped.txt
index 4f7f5b2..e0db246 100644
--- a/MarkupString.Ansi/PublicAPI.Unshipped.txt
+++ b/MarkupString.Ansi/PublicAPI.Unshipped.txt
@@ -52,3 +52,39 @@ static MarkupString.Ansi.Decoding.VtDecoding.WithVt(this MarkupString.Decoding.D
 virtual MarkupString.Ansi.Decoding.AnsiColors.Legible(MarkupString.RgbColor foreground, MarkupString.RgbColor background) -> MarkupString.RgbColor
 virtual MarkupString.Ansi.Decoding.AnsiColors.Standard(int index, bool bright) -> MarkupString.RgbColor
 virtual MarkupString.Ansi.Decoding.AnsiColors.Xterm(int index) -> MarkupString.RgbColor
+MarkupString.Ansi.Decoding.PictureDecoding
+MarkupString.Ansi.Decoding.PictureStore
+MarkupString.Ansi.Decoding.PictureStore.Add(int width, int height, byte[]! rgba) -> MarkupString.Ansi.Decoding.StoredPicture!
+MarkupString.Ansi.Decoding.PictureStore.Add(int width, int height, byte[]? rgba, System.ReadOnlyMemory<byte> encoded, string? mediaType) -> MarkupString.Ansi.Decoding.StoredPicture!
+MarkupString.Ansi.Decoding.PictureStore.Added -> System.Action<MarkupString.Ansi.Decoding.StoredPicture!>?
+MarkupString.Ansi.Decoding.PictureStore.Budget.get -> long
+MarkupString.Ansi.Decoding.PictureStore.Budget.set -> void
+MarkupString.Ansi.Decoding.PictureStore.Count.get -> int
+MarkupString.Ansi.Decoding.PictureStore.MarkTransmitted(uint imageId) -> bool
+MarkupString.Ansi.Decoding.PictureStore.MaxPixels.get -> long
+MarkupString.Ansi.Decoding.PictureStore.MaxPixels.set -> void
+MarkupString.Ansi.Decoding.PictureStore.PictureStore() -> void
+MarkupString.Ansi.Decoding.PictureStore.Remove(string! key) -> bool
+MarkupString.Ansi.Decoding.PictureStore.TryGet(MarkupString.ImageMarkup! image, out MarkupString.Ansi.Decoding.StoredPicture? picture) -> bool
+MarkupString.Ansi.Decoding.PictureStore.TryGet(string! key, out MarkupString.Ansi.Decoding.StoredPicture? picture) -> bool
+MarkupString.Ansi.Decoding.PictureStore.TryGetPicture(MarkupString.ImageMarkup! image, out MarkupString.Ansi.TerminalPicture? picture) -> bool
+MarkupString.Ansi.Decoding.PictureStore.Used.get -> long
+MarkupString.Ansi.Decoding.PicturesPlugin
+MarkupString.Ansi.Decoding.PicturesPlugin.Name.get -> string!
+MarkupString.Ansi.Decoding.PicturesPlugin.Register(MarkupString.Decoding.DecoderBuilder! builder) -> void
+MarkupString.Ansi.Decoding.StoredPicture
+MarkupString.Ansi.Decoding.StoredPicture.Encoded.get -> System.ReadOnlyMemory<byte>
+MarkupString.Ansi.Decoding.StoredPicture.Height.get -> int
+MarkupString.Ansi.Decoding.StoredPicture.Key.get -> string!
+MarkupString.Ansi.Decoding.StoredPicture.MediaType.get -> string?
+MarkupString.Ansi.Decoding.StoredPicture.Pixels.get -> MarkupString.Ansi.TerminalPicture?
+MarkupString.Ansi.Decoding.StoredPicture.Size.get -> long
+MarkupString.Ansi.Decoding.StoredPicture.Source.get -> string!
+MarkupString.Ansi.Decoding.StoredPicture.ToDataUrl() -> string!
+MarkupString.Ansi.Decoding.StoredPicture.Width.get -> int
+const MarkupString.Ansi.Decoding.PictureStore.Scheme = "picture:" -> string!
+const MarkupString.Ansi.Decoding.PicturesPlugin.MaxTransmission = 16777216 -> int
+static MarkupString.Ansi.Decoding.PictureDecoding.Pictures(this MarkupString.Decoding.Decoder! decoder) -> MarkupString.Ansi.Decoding.PictureStore!
+static MarkupString.Ansi.Decoding.PictureDecoding.WithPictures(this MarkupString.Decoding.DecoderRegistry! registry) -> MarkupString.Decoding.DecoderRegistry!
+static MarkupString.Ansi.Decoding.PicturesPlugin.Instance.get -> MarkupString.Ansi.Decoding.PicturesPlugin!
+static MarkupString.Ansi.Decoding.PicturesPlugin.Pictures(MarkupString.Decoding.Decoder! decoder) -> MarkupString.Ansi.Decoding.PictureStore!
diff --git a/MarkupString.Tests/Decoding/PictureDecodingTests.cs b/MarkupString.Tests/Decoding/PictureDecodingTests.cs
new file mode 100644
index 0000000..80526bd
--- /dev/null
+++ b/MarkupString.Tests/Decoding/PictureDecodingTests.cs
@@ -0,0 +1,238 @@
+using System.Diagnostics.CodeAnalysis;
+using MarkupString.Ansi;
+using MarkupString.Ansi.Decoding;
+using MarkupString.Decoding;
+using MarkupString.Display;
+using MarkupString.Layout;
+
+/// <summary>Pictures read back from what this package writes for each terminal, and from what other programs send.</summary>
+public class PictureDecodingTests
+{
+	private static readonly DecoderRegistry Registry = VtDecoding.Terminal.WithPictures();
+	private static readonly ImageMarkup Cat = new("cat.png", "A cat");
+
+	private sealed class Source(TerminalPicture picture) : ITerminalPictureSource
+	{
+		public bool TryGetPicture(ImageMarkup image, [NotNullWhen(true)] out TerminalPicture? found)
+		{
+			found = picture;
+			return true;
+		}
+
+		public bool MarkTransmitted(uint imageId) => true;
+	}
+
+	/// <summary>Red on the left, blue on the right, opaque.</summary>
+	private static TerminalPicture RedBlue(int width = 4, int height = 4)
+	{
+		var rgba = new byte[width * height * 4];
+		for (var y = 0; y < height; y++)
+		{
+			for (var x = 0; x < width; x++)
+			{
+				var o = (y * width + x) * 4;
+				if (x < width / 2) rgba[o] = 255;
+				else rgba[o + 2] = 255;
+				rgba[o + 3] = 255;
+			}
+		}
+
+		return new TerminalPicture("red-blue", width, height, rgba);
+	}
+
+	/// <summary>A figure of the picture in 4 × 2 cells, then a line of text, written for <paramref name="features"/>.</summary>
+	private static string Wire(TerminalFeatures features, TerminalPicture picture)
+	{
+		var laid = BlockLayout.Build(new Figure(Cat, MarkupText.Empty), 10, context: new LayoutContext { Pictures = (_, _) => new PictureCells(4, 2) });
+		var options = new AnsiOutputOptions(Features: features) { Pictures = new Source(picture), CellWidth = 8, CellHeight = 16 };
+		return laid.Render(MarkupFormat.Ansi, MarkupRegistry.Empty.WithAnsi().WithAnsiOutput(options)) + "\nafter\n";
+	}
+
+	private static (IReadOnlyList<DisplayLine> Lines, Decoder Decoder) Decode(string wire)
+	{
+		var decoder = Registry.CreateDecoder();
+		var lines = new List<DisplayLine>(decoder.Feed(wire));
+		if (decoder.HasPendingLine) lines.Add(decoder.EndLine());
+		return (lines, decoder);
+	}
+
+	/// <summary>The picture rows on each line: (row, rows, columns, first column, cells).</summary>
+	private static List<(int Row, int Rows, int Columns, int Cells)> PictureRows(IReadOnlyList<DisplayLine> lines)
+	{
+		var rows = new List<(int, int, int, int)>();
+		foreach (var line in lines)
+		{
+			var layout = CellRenderer.Layout(line.Content, 0, AnsiDisplay.Default, new DisplayOptions());
+			var cells = layout.Rows.SelectMany(row => row.Cells).Where(cell => cell.Style.Picture?.Row is not null).ToList();
+			if (cells.Count == 0) continue;
+			var row = cells[0].Style.Picture!.Row!.Value;
+			rows.Add((row.Row, row.Rows, row.Columns, cells.Count));
+		}
+
+		return rows;
+	}
+
+	private static async Task AssertSamePixels(StoredPicture stored, TerminalPicture expected)
+	{
+		await Assert.That(stored.Pixels).IsNotNull();
+		await Assert.That(stored.Width).IsEqualTo(expected.Width);
+		await Assert.That(stored.Height).IsEqualTo(expected.Height);
+		await Assert.That(stored.Pixels!.Rgba.ToArray()).IsEquivalentTo(expected.Rgba.ToArray());
+	}
+
+	[Test]
+	public async Task Kitty_Placeholders_RoundTrip()
+	{
+		var picture = RedBlue();
+		var (lines, decoder) = Decode(Wire(TerminalFeatures.KittyGraphics, picture));
+
+		await Assert.That(PictureRows(lines)).IsEquivalentTo([(0, 2, 4, 4), (1, 2, 4, 4)]);
+		await Assert.That(decoder.Pictures().Count).IsEqualTo(1);
+		var image = lines.SelectMany(line => line.Content.Runs).SelectMany(run => run.Markups).OfType<ImageMarkup>().First();
+		await Assert.That(decoder.Pictures().TryGet(image, out var stored)).IsTrue();
+		await AssertSamePixels(stored!, picture);
+		await Assert.That(lines[^1].Content.ToPlainText()).IsEqualTo("after");
+		await Assert.That(decoder.Diagnostics.PicturesFailed).IsEqualTo(0);
+	}
+
+	[Test]
+	public async Task InlineImages_Overlay_RoundTrip()
+	{
+		var picture = RedBlue();
+		var (lines, decoder) = Decode(Wire(TerminalFeatures.InlineImages, picture));
+
+		await Assert.That(PictureRows(lines)).IsEquivalentTo([(0, 2, 4, 4), (1, 2, 4, 4)]);
+		await Assert.That(decoder.Pictures().TryGet(lines[0].Content.Runs.SelectMany(run => run.Markups).OfType<ImageMarkup>().First(), out var stored)).IsTrue();
+		await AssertSamePixels(stored!, picture);
+		await Assert.That(stored!.MediaType).IsEqualTo("image/png");
+		await Assert.That(lines[^1].Content.ToPlainText()).IsEqualTo("after");
+	}
+
+	[Test]
+	public async Task Sixel_Overlay_RoundTrip()
+	{
+		var picture = RedBlue(16, 12);
+		var (lines, decoder) = Decode(Wire(TerminalFeatures.Sixel, picture));
+
+		var rows = PictureRows(lines);
+		await Assert.That(rows.Select(row => row.Row)).IsEquivalentTo([0, 1]);
+		await Assert.That(rows.All(row => row.Columns == 4 && row.Cells == 4)).IsTrue();
+		await Assert.That(decoder.Pictures().Count).IsEqualTo(1);
+		await Assert.That(lines[^1].Content.ToPlainText()).IsEqualTo("after");
+		await Assert.That(decoder.Diagnostics.PicturesFailed).IsEqualTo(0);
+	}
+
+	[Test]
+	public async Task Sixel_DecodesColoursAndSize()
+	{
+		// Two colours, red in the left column and blue in the right, six pixels tall, raster 2 × 6.
+		var (lines, decoder) = Decode("\eP0;1q\"1;1;2;6#1;2;100;0;0#2;2;0;0;100#1~$#2?~\e\\");
+		var stored = decoder.Pictures().TryGet(lines[0].Content.Runs.SelectMany(run => run.Markups).OfType<ImageMarkup>().First(), out var found) ? found : null;
+		await Assert.That(stored!.Width).IsEqualTo(2);
+		await Assert.That(stored.Height).IsEqualTo(6);
+		var rgba = stored.Pixels!.Rgba.ToArray();
+		await Assert.That(rgba[..4]).IsEquivalentTo(new byte[] { 255, 0, 0, 255 });
+		await Assert.That(rgba[4..8]).IsEquivalentTo(new byte[] { 0, 0, 255, 255 });
+	}
+
+	[Test]
+	public async Task Kitty_PlacedImage_TakesRowsAndMovesTheCursor()
+	{
+		// a=T without placeholders: 16 × 32 pixels of RGB at 8 × 16 cells is 2 × 2 cells.
+		var rgb = Convert.ToBase64String(new byte[16 * 32 * 3]);
+		var (lines, _) = Decode($"ab\e_Ga=T,f=24,s=16,v=32;{rgb}\e\\cd\n");
+		await Assert.That(lines.Count).IsEqualTo(3);
+		await Assert.That(PictureRows(lines)).IsEquivalentTo([(0, 2, 2, 2), (1, 2, 2, 2)]);
+		await Assert.That(lines[0].Content.ToPlainText()).IsEqualTo("ab  ");
+		await Assert.That(lines[2].Content.ToPlainText()).IsEqualTo("    cd");
+	}
+
+	[Test]
+	public async Task Kitty_Chunks_AndReplies()
+	{
+		var bytes = Convert.ToBase64String(new byte[8 * 16 * 4]);
+		var decoder = Registry.CreateDecoder();
+		var replies = new List<string>();
+		decoder.EventRaised += e => { if (e is ReplyEvent reply) replies.Add(reply.Text); };
+		decoder.Feed($"\e_Ga=t,i=7,s=8,v=16,m=1;{bytes[..100]}\e\\\e_Gm=1;{bytes[100..200]}\e\\\e_Gm=0;{bytes[200..]}\e\\");
+		decoder.Feed("\e_Ga=p,i=7\e\\");
+		decoder.Feed("\e_Ga=p,i=9\e\\");
+		decoder.Feed("\e_Ga=t,t=f,i=8;L3RtcC94\e\\");
+		await Assert.That(replies).IsEquivalentTo([
+			"\e_Gi=7;OK\e\\",
+			"\e_Gi=7;OK\e\\",
+			"\e_Gi=9;ENOENT:no such image\e\\",
+			"\e_Gi=8;EINVAL:only direct transmission is read\e\\",
+		]);
+		await Assert.That(decoder.Pictures().Count).IsEqualTo(1);
+	}
+
+	[Test]
+	public async Task Kitty_Quiet_SendsNothing()
+	{
+		var decoder = Registry.CreateDecoder();
+		var replies = 0;
+		decoder.EventRaised += e => { if (e is ReplyEvent) replies++; };
+		decoder.Feed($"\e_Ga=t,i=7,s=1,v=1,q=2;{Convert.ToBase64String(new byte[4])}\e\\");
+		await Assert.That(replies).IsEqualTo(0);
+	}
+
+	[Test]
+	public async Task InlineImage_NotInline_IsADownload()
+	{
+		var decoder = Registry.CreateDecoder();
+		var events = new List<DecodeEvent>();
+		decoder.EventRaised += events.Add;
+		decoder.Feed($"\e]1337;File=name={Convert.ToBase64String("a.txt"u8.ToArray())};size=3:{Convert.ToBase64String("abc"u8.ToArray())}\a");
+		await Assert.That(events.OfType<DownloadEvent>().Single()).IsEqualTo(new DownloadEvent("a.txt", 3));
+		await Assert.That(decoder.Pictures().Count).IsEqualTo(0);
+	}
+
+	[Test]
+	public async Task InlineImage_Gif_IsKeptForABrowser()
+	{
+		// A 1 × 1 GIF; its size comes from the header.
+		var gif = Convert.FromBase64String("R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7");
+		var decoder = Registry.CreateDecoder();
+		var lines = decoder.Feed($"\e]1337;File=inline=1;width=3:{Convert.ToBase64String(gif)}\a\n");
+		var image = lines[0].Content.Runs.SelectMany(run => run.Markups).OfType<ImageMarkup>().Single();
+		await Assert.That(decoder.Pictures().TryGet(image, out var stored)).IsTrue();
+		await Assert.That(stored!.Pixels).IsNull();
+		await Assert.That(stored.MediaType).IsEqualTo("image/gif");
+		await Assert.That(stored.ToDataUrl()).StartsWith("data:image/gif;base64,R0lGOD");
+		await Assert.That(image.Row!.Value.Columns).IsEqualTo(3);
+	}
+
+	[Test]
+	public async Task Store_EvictsTheLeastRecentlyUsed()
+	{
+		var store = new PictureStore { Budget = 100 };
+		var first = store.Add(4, 4, new byte[64]);
+		var second = store.Add(4, 4, Enumerable.Repeat((byte)1, 64).ToArray());
+		await Assert.That(store.TryGet(first.Key, out _)).IsFalse();
+		await Assert.That(store.TryGet(second.Key, out _)).IsTrue();
+		await Assert.That(store.Used).IsEqualTo(64);
+	}
+
+	[Test]
+	public async Task Store_SamePictureTwice_IsOne()
+	{
+		var store = new PictureStore();
+		var a = store.Add(1, 1, [1, 2, 3, 4]);
+		var b = store.Add(1, 1, [1, 2, 3, 4]);
+		await Assert.That(b).IsSameReferenceAs(a);
+		await Assert.That(store.Count).IsEqualTo(1);
+	}
+
+	[Test]
+	public async Task Png_DecodesPaletteAndInterlace()
+	{
+		// 2 × 2 interlaced palette PNG: red, green / blue, white.
+		var png = Convert.FromBase64String("iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAMAAAEyb82AAAAADFBMVEX/AAAA/wAAAP/////7AGD2AAAAD0lEQVR4nGNgYGBkYGIGAAASAAe4hQWPAAAAAElFTkSuQmCC");
+		var decoder = Registry.CreateDecoder();
+		var lines = decoder.Feed($"\e]1337;File=inline=1:{Convert.ToBase64String(png)}\a\n");
+		var image = lines[0].Content.Runs.SelectMany(run => run.Markups).OfType<ImageMarkup>().Single();
+		await Assert.That(decoder.Pictures().TryGet(image, out var stored)).IsTrue();
+		await Assert.That(stored!.Pixels!.Rgba.ToArray()).IsEquivalentTo(new byte[] { 255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255, 255, 255, 255, 255 });
+	}
+}
diff --git a/MarkupString/Decoding/Decoder.cs b/MarkupString/Decoding/Decoder.cs
index 4e2144c..acb89ca 100644
--- a/MarkupString/Decoding/Decoder.cs
+++ b/MarkupString/Decoding/Decoder.cs
@@ -54,6 +54,9 @@ internal Decoder(DecoderRegistry registry, DecoderOptions options)
 
 	internal DecodeContext Context { get; }
 
+	/// <summary>This decoder's instance of a plugin's state, as <see cref="DecodeContext.State{T}"/> gives it to the plugin.</summary>
+	public T State<T>() where T : class, new() => Context.State<T>();
+
 	/// <summary>Reads <paramref name="text"/> and returns the lines it completed.</summary>
 	public IReadOnlyList<DisplayLine> Feed(ReadOnlySpan<char> text)
 	{
@@ -225,17 +228,17 @@ public void Apc(ReadOnlySpan<char> payload)
 public sealed class DecodeDiagnostics
 {
 	/// <summary>Sequences that were malformed, too long, or cut off by a line ending.</summary>
-	public int AbandonedSequences { get; internal set; }
+	public int AbandonedSequences { get; set; }
 
 	/// <summary>Well-formed sequences no handler claimed.</summary>
-	public int UnhandledSequences { get; internal set; }
+	public int UnhandledSequences { get; set; }
 
 	/// <summary>Control characters no handler claimed.</summary>
-	public int UnhandledControls { get; internal set; }
+	public int UnhandledControls { get; set; }
 
 	/// <summary>Things dropped because a limit was reached: an element stack, a line length, a picture size.</summary>
-	public int LimitsReached { get; internal set; }
+	public int LimitsReached { get; set; }
 
 	/// <summary>Pictures that could not be decoded.</summary>
-	public int PicturesFailed { get; internal set; }
+	public int PicturesFailed { get; set; }
 }
diff --git a/MarkupString/PublicAPI.Unshipped.txt b/MarkupString/PublicAPI.Unshipped.txt
index 8ba3d4f..fbf8ea7 100644
--- a/MarkupString/PublicAPI.Unshipped.txt
+++ b/MarkupString/PublicAPI.Unshipped.txt
@@ -667,3 +667,9 @@ static MarkupString.HighlightMarkup.operator ==(MarkupString.HighlightMarkup? le
 ~override MarkupString.Display.DisplaySpan.ToString() -> string
 ~override MarkupString.Display.DisplayStyle.Equals(object obj) -> bool
 ~override MarkupString.Display.DisplayStyle.ToString() -> string
+MarkupString.Decoding.Decoder.State<T>() -> T!
+MarkupString.Decoding.DecodeDiagnostics.AbandonedSequences.set -> void
+MarkupString.Decoding.DecodeDiagnostics.LimitsReached.set -> void
+MarkupString.Decoding.DecodeDiagnostics.PicturesFailed.set -> void
+MarkupString.Decoding.DecodeDiagnostics.UnhandledControls.set -> void
+MarkupString.Decoding.DecodeDiagnostics.UnhandledSequences.set -> void
diff --git a/README.md b/README.md
index 5352f79..8cf48c3 100644
--- a/README.md
+++ b/README.md
@@ -228,6 +228,8 @@ reflection hidden behind convenience APIs.
 | [Formats and rendering](docs/formats.md) | Built-in formats, shared vocabulary, framers, untrusted tags, and custom formats. |
 | [Custom markup kinds](docs/custom-markup.md) | Implementing an `IMarkup`, emitter, and codec. |
 | [Serialization](docs/serialization.md) | JSON wire format, forward compatibility, and `UnknownMarkup`. |
+| [Decoding](docs/decoding.md) | Reading server output: ANSI and VT sequences, OSC, events, replies, limits, and plugins. |
+| [Display](docs/display.md) | Output capabilities, degrading, spans for a web page, and cell grids with hit testing. |
 | [Releasing](docs/releasing.md) | Versioning and publishing for maintainers. |
 
 ## Requirements
diff --git a/docs/decoding.md b/docs/decoding.md
new file mode 100644
index 0000000..31c0620
--- /dev/null
+++ b/docs/decoding.md
@@ -0,0 +1,465 @@
+# Decoding server output
+
+A `Decoder` reads what a server sends (text with ANSI and VT sequences mixed in) and turns it into
+`MarkupText` lines. Styling becomes markup runs, so a decoded line renders, measures, wraps and
+serializes like any other `MarkupText`. Rendering a line for an output is covered in
+[Display](display.md).
+
+```csharp
+using MarkupString;
+using MarkupString.Ansi;
+using MarkupString.Ansi.Decoding;
+using MarkupString.Decoding;
+
+MarkupRegistry.Default = MarkupRegistry.Empty.WithAnsi();
+
+// Once, at startup: which protocols to read.
+var registry = DecoderRegistry.Empty.WithVt();
+
+// One per connection: it holds that connection's style, half-read sequences and pending line.
+var decoder = registry.CreateDecoder(new DecoderOptions
+{
+    Identity = new ClientIdentity { Name = "MyClient", Version = "2.1", Columns = 100, Rows = 40 },
+});
+
+var replies = new List<string>();   // send each of these to the server
+decoder.EventRaised += e =>
+{
+    switch (e)
+    {
+        case ReplyEvent reply: replies.Add(reply.Text); break;
+        case TitleEvent title: Console.WriteLine($"title: {title.Title}"); break;
+    }
+};
+
+foreach (var line in decoder.Feed("\e]2;The Hall\a\e[1;33mWelcome\e[0m back.\r\nExits: north\e[c\r\n> "))
+{
+    Console.WriteLine($"{line.Sequence}: {line.Content.Render(MarkupFormat.Ansi)}");
+}
+
+// The telnet layer saw GA or EOR.
+if (decoder.EndPrompt() is { } prompt) Console.WriteLine($"prompt: {prompt.Content}");
+```
+
+```
+title: The Hall
+0: \e[1;33mWelcome\e[0m back.
+1: Exits: north
+prompt: >
+```
+
+Output in this guide shows ESC as `\e` and BEL as `\a`. Events are raised while `Feed` reads,
+before it returns the lines. The `\e[c` on the second line
+asked for device attributes, so `replies` holds `\e[?62;22c`.
+
+The registry is immutable and shared. A decoder is not safe to use from two threads at once.
+
+## Lines
+
+`Feed` returns the lines its text completed, which may be none. A line ends at a line feed in the
+text. Whatever is left is the pending line (`PendingLine`, `HasPendingLine`), and a sequence cut in
+half by a packet boundary is finished by the next `Feed`:
+
+```csharp
+var decoder = registry.CreateDecoder();
+decoder.Feed("\e[3");             // no lines
+decoder.Feed("1mred\n");          // \e[31mred\e[0m
+decoder.Feed("still red\n");      // \e[31mstill red\e[0m
+```
+
+The style carries from line to line, as it does on a terminal. Each line is rendered closed, so it
+stands alone in scrollback.
+
+Two calls end a line for the host:
+
+| Call | When | Returns |
+|---|---|---|
+| `EndLine()` | Your telnet layer strips line terminators and knows where a line ended | The line, even when empty |
+| `EndPrompt()` | Telnet GA or EOR | The line with `Kind = LineKind.Prompt`, or null when nothing was read |
+
+Both abandon a sequence still in flight. `Decoder.DecodeAll(text, registry)` decodes a whole string
+at once and includes a last line that has no line break:
+
+```csharp
+foreach (var line in Decoder.DecodeAll("one\ntwo", registry))
+    Console.WriteLine($"{line.Kind} {line.Content}");
+```
+
+```
+Output one
+Output two
+```
+
+A `DisplayLine` carries `Content`, `Kind`, `Sequence` (its number within the decoder, from 0, for
+keying a view) and `Destination` (the pane it was sent to, or null for the main output).
+
+`Reset()` forgets the style, open elements, half-read sequences and the pending line. Set
+`decoder.Identity` again when the pane is resized; answers read it each time.
+
+## Events
+
+Anything that is not text to show is raised through `EventRaised`, as it is found.
+
+| Event | Raised for |
+|---|---|
+| `ReplyEvent(Text)` | An answer to a query. Send `Text` to the server exactly as it is. |
+| `TitleEvent(Title, Icon)` | OSC 0, 1, 2. `Icon` is true for 0 and 1. |
+| `PaletteEvent(Slot, Index, Color)` | OSC 4, 10, 11, 12 set a colour; 104, 110, 111, 112 reset one (`Color` null). |
+| `ClipboardEvent(Selection, Text)` | OSC 52. `Text` is null when the server asked to read the clipboard. |
+| `ProtocolEvent(Name, Active)` | A text protocol was turned on or off. |
+| `VariableEvent(Name, Value)` | A server variable (MXP). |
+| `DownloadEvent(Name, Size)` | A file offered to save (iTerm2 `inline=0`). The decoder never saves it. |
+
+The decoder acts on none of these. Refuse a clipboard write unless the player allowed it.
+
+## What the terminal plugins read
+
+`WithVt()` adds five plugins. `VtDecoding.Terminal` is a registry with just these.
+
+### `SgrPlugin` (`CSI … m`)
+
+| Codes | Effect |
+|---|---|
+| empty, `0` | Reset |
+| `1`, `2`, `3` | Bold, faint, italic |
+| `4`, `21` | Underline. `4:0` turns it off; `4:1` to `4:5` are all drawn as one underline. |
+| `5`, `6` | Blink |
+| `7`, `8`, `9` | Inverse, conceal, strikethrough |
+| `22` | Neither bold nor faint |
+| `23`, `24`, `25`, `27`, `28`, `29` | Turn off italic, underline, blink, inverse, conceal, strikethrough |
+| `30`–`37`, `90`–`97` | Standard foreground, bright for 90–97 |
+| `40`–`47`, `100`–`107` | Standard background, bright for 100–107 |
+| `38`, `48` | Extended colour: `5;n`, `2;r;g;b`, and the colon forms `5:n`, `2:r:g:b`, `2::r:g:b`, `2:cs:r:g:b` |
+| `39`, `49` | Default foreground, background |
+| `53`, `55` | Overline on, off |
+| `58` | Underline colour: its parameters are read and dropped |
+
+Any other code is ignored. An extended colour out of range leaves the colour as it was. The style
+is written under the `VtPens.Style` pen as an `AnsiMarkup`.
+
+### `ControlsPlugin`
+
+| Input | Effect |
+|---|---|
+| BEL | A `BellMarkup` point |
+| CR | Cursor to column 0 |
+| BS | Cursor one cell left, stopping at 0 |
+| HT | Cursor to the next multiple of 8 (`ControlsPlugin.TabStop`) |
+| FF | A `ClearScreenMarkup` point |
+| VT | Ends the line |
+| `CSI K` | `0` erase to end of line, `1` blank to the cursor, `2` erase the line. Other values are not claimed. |
+| `CSI J` | `2` or `3` writes a `ClearScreenMarkup` point. `0` and `1` are claimed and do nothing: a scrolling pane has no screen below the cursor. |
+| `CSI G`, ``CSI ` `` | Cursor to column n (from 1) |
+| `CSI C`, `CSI D` | Cursor n cells right, left |
+| `ESC 7`, `ESC 8` | Save the cursor's column, and go back to it |
+| `CSI A`, `ESC D`, `ESC M` | Claimed and ignored: a scrolling pane cannot go up a line, or down one without ending it |
+
+A line feed always ends the line, with or without this plugin. DEL is dropped. C1 controls
+(U+0080 to U+009F) are text, as xterm treats them in UTF-8. CAN and SUB cancel a sequence in flight.
+
+### `CharsetPlugin`
+
+`ESC ( 0` and `ESC ) 0` designate the DEC special graphics set into G0 or G1; `ESC ( B` and
+`ESC ) B` put ASCII back. SO and SI shift between G0 and G1. While graphics is in force, `_` to `~`
+become line drawing and symbols:
+
+```csharp
+Decoder.DecodeAll("\e(0lqqk\e(B ok", registry)[0].Content;  // ┌──┐ ok
+```
+
+### `OscPlugin`
+
+| OSC | Effect |
+|---|---|
+| `0`, `1`, `2` | `TitleEvent`, control characters removed |
+| `4;n;spec…` | `PaletteEvent` for each index and colour pair |
+| `104` | Reset the listed entries, or every entry (`Index = -1`) when empty |
+| `10`, `11`, `12` | Set the foreground, background, cursor colour, or answer `?` (10 and 11 only). `10;a;b` sets 10 and 11 at once. |
+| `110`, `111`, `112` | Reset them |
+| `52;sel;base64` | `ClipboardEvent` with the decoded text, or a null text for `?`. Invalid base64 is dropped. |
+| `8;params;uri` | A link over the text that follows, until an empty uri. An address longer than 2083 characters, or one `UrlSafety.IsSafeNavigableUrl` refuses (`javascript:` and the like), ends the link instead. |
+| `68;1;SEND;command` | An MSLP command link over the underlined text that follows. Turning the underline off ends it. |
+
+Colours are X11 specs: `rgb:r/g/b` with one to four hex digits a channel, or `#rgb`, `#rrggbb`,
+`#rrrgggbbb`, `#rrrrggggbbbb`. `OscPlugin.ParseColor` and `FormatColor` are public. Links are
+written under the `VtPens.Link` pen.
+
+### `AnswersPlugin`
+
+| Query | Reply | Allowed by |
+|---|---|---|
+| `CSI c`, `CSI 0 c` | `\e[?62;22c`, or `\e[?62;4;22c` when `Identity.Output.Pictures` has `Sixel` | `Identity` |
+| `CSI > q` | `\eP>\|Name Version\e\\` (XTVERSION) | `Identity` |
+| `CSI 5 n` | `\e[0n` | `Identity` |
+| `CSI 14 t`, `16 t`, `18 t` | The pane in pixels, a cell in pixels, the pane in cells | `Size` |
+| `OSC 10 ; ?`, `OSC 11 ; ?` | `Identity.Foreground`, `Background` as `rgb:rrrr/gggg/bbbb`, when set | `Colors` |
+| `CSI 6 n` | `\e[{Rows};{column + 1}R` | `CursorPosition` |
+
+A query whose answer is not allowed is still claimed, and nothing is sent.
+
+## Overwriting
+
+A carriage return or backspace moves the cursor back, and what is written next overwrites cells in
+place. A progress bar redrawn over itself ends as its last state.
+
+| Input | Line |
+|---|---|
+| `Loading 10%\rLoading 100%` | `Loading 100%` |
+| `abcdef\rXY` | `XYcdef` |
+| `abc\b\bX` | `aXc` |
+| `hello world\r\e[Kbye` | `bye` |
+| `a\tb` | `a       b` |
+| `a\e[10Gb` | `a        b` |
+
+Moving the cursor past the end of the line pads with spaces only when text follows, so a tab at the
+end of a line leaves no trailing blanks. The style of overwritten cells is replaced with the new text's.
+
+## Limits and diagnostics
+
+Every buffer has a cap. `VtLimits` holds the tokenizer's:
+
+| Property | Default | |
+|---|---|---|
+| `MaxParameters` | 32 | Parameters in a CSI or DCS header, subparameters included |
+| `MaxParameterValue` | 65535 | Larger values are clamped |
+| `MaxStringLength` | 16 MiB | An OSC or DCS payload |
+| `MaxApcLength` | 64 KiB | An APC payload |
+
+A sequence that overflows is read to its end and dropped. A line feed ends any sequence in flight,
+so a bare `ESC ]` typed into a channel cannot swallow the rest of the session.
+
+`DecoderOptions` holds the decoder's:
+
+| Property | Default | |
+|---|---|---|
+| `MaxOpenElements` | 64 | Elements a text protocol may have open at once |
+| `MaxLineLength` | 65536 | Characters in a line. Text that would take the line past it is dropped. |
+
+`decoder.Diagnostics` counts what was dropped:
+
+```csharp
+var decoder = registry.CreateDecoder();
+decoder.Feed("\e[?25lHello\e]0;never closed\nworld\u0001\n");
+// AbandonedSequences = 1   the OSC cut off by the line feed
+// UnhandledSequences = 1   CSI ? 25 l, which no plugin claims
+// UnhandledControls  = 1   U+0001
+```
+
+`LimitsReached` counts text and elements dropped at a limit. `PicturesFailed` counts pictures that
+could not be decoded.
+
+## Client identity and answers
+
+`ClientIdentity` is what the decoder answers with: `Name`, `Version`, `Columns`, `Rows`,
+`CellWidth` and `CellHeight` (8 by 16 by default), `Foreground`, `Background`, and `Output`, the
+`OutputCapabilities` of where the session is shown.
+
+`Answers` says which questions get an answer. `ClientAnswers.Default` is everything except
+`CursorPosition`. A server that sends `CSI 6 n` assumes a full screen it can address, and a scrolling
+pane is not one: the reply always gives the last row. Turn it on for a server you know uses it only
+to find the column:
+
+```csharp
+var decoder = registry.CreateDecoder(new DecoderOptions
+{
+    Identity = new ClientIdentity
+    {
+        Answers = ClientAnswers.Default | ClientAnswers.CursorPosition,
+        Background = new RgbColor(0, 0, 0),
+    },
+});
+decoder.Feed("\e[c\e[>q\e[18t\e]11;?\a> \e[6n");
+```
+
+The replies, in order:
+
+```
+\e[?62;22c
+\eP>|MarkupString 1.0\e\
+\e[8;24;80t
+\e]11;rgb:0000/0000/0000\e\
+\e[24;3R
+```
+
+`ClientAnswers.None` answers nothing.
+
+## MTTS
+
+`ToMtts` gives the bits for the last step of the telnet TTYPE cycle, from `Output`:
+
+| Bit | Set when |
+|---|---|
+| `Vt100`, `Utf8` | Always, but `Utf8` is cleared for `UnicodeLevel.Ascii` |
+| `Ansi` | `Colors` is `Standard` or better |
+| `Colors256`, `OscColorPalette` | `Xterm256` or better |
+| `TrueColor` | `TrueColor` |
+| `Mslp` | `Interactions` has `Command` |
+| `ScreenReader`, `Ssl` | You pass `screenReader: true`, `tls: true` |
+
+```csharp
+var identity = new ClientIdentity { Output = OutputCapabilities.Browser };
+identity.ToMtts(tls: true);        // Ansi, Vt100, Utf8, Colors256, OscColorPalette, TrueColor, Mslp, Ssl
+(int)identity.ToMtts(tls: true);   // 3375, sent as "MTTS 3375"
+```
+
+The default `Output` is `OutputCapabilities.PlainText`, which gives only `Vt100, Utf8`.
+
+## Writing a plugin
+
+A plugin is an `IDecoderPlugin`: a name and a `Register` method that adds handlers to a
+`DecoderBuilder`.
+
+```csharp
+sealed class CursorPlugin : IDecoderPlugin
+{
+    public string Name => "cursor";
+
+    // A scrolling pane has no cursor to show or hide: claim CSI ? 25 h and CSI ? 25 l so they are not counted.
+    public void Register(DecoderBuilder builder) => builder
+        .OnCsi('h', static (in CsiSequence sequence, DecodeContext context) => sequence.Get(0) == 25, prefix: '?')
+        .OnCsi('l', static (in CsiSequence sequence, DecodeContext context) => sequence.Get(0) == 25, prefix: '?');
+}
+
+var registry = DecoderRegistry.Empty.WithVt().With(new CursorPlugin());
+```
+
+| Method | Handles |
+|---|---|
+| `OnCsi(final, handler, prefix, intermediates)` | A control sequence |
+| `OnEsc(final, handler, intermediates)` | An escape sequence |
+| `OnOsc(number, handler)` | An OSC; the handler gets what follows the number and `;` |
+| `OnDcs(final, handler, prefix, intermediates)` | A device control string |
+| `OnApc(handler)` | Every APC, until one handler claims it |
+| `OnControl(c, handler)` | A C0 control |
+| `OnPrint(filter)` | Printable text before it is written; return true when the filter wrote it |
+| `OnLineEnd(action)` | Every line end, after the active text protocol's `EndLine` |
+| `TextProtocol(name, create)` | A protocol carried in the text, such as MXP |
+
+`CsiSequence.Get(index, fallback)` reads a parameter, giving `fallback` when it is missing or empty.
+`IsSubparameter(index)` says whether it followed a `:`. `Is(final, prefix)` tests the sequence's name.
+
+`registry.With(plugin)` replaces a plugin of the same name. `Has(name)` and `Plugins` list what is
+installed.
+
+### Handler order
+
+For one sequence, the newest handler is tried first: handlers from a plugin added later run before
+an earlier plugin's, and within a plugin a later call runs before an earlier one. A handler returns
+true to claim the sequence and false to pass it to the next older handler. A sequence nobody claims
+is counted in `UnhandledSequences`.
+
+This lets a plugin change one case of a sequence and leave the rest alone:
+
+```csharp
+sealed class BellCount
+{
+    public int Rung { get; set; }
+}
+
+sealed class QuietBellPlugin : IDecoderPlugin
+{
+    public string Name => "quiet-bell";
+
+    // Added after WithVt, so it sees each bell before ControlsPlugin does.
+    public void Register(DecoderBuilder builder) => builder.OnControl('\a', static (_, context) =>
+    {
+        var bells = context.State<BellCount>();
+        bells.Rung++;
+        return bells.Rung > 1;   // true swallows it; false lets ControlsPlugin write the bell
+    });
+}
+```
+
+Line end handlers are the exception: they all run, in the order they were added.
+
+### Per-connection state
+
+The plugin instance is shared by every decoder of the registry, so it holds no state of its own.
+`context.State<T>()` gives this decoder's instance of `T`, made on first use and cleared by
+`Reset()`. The host can read the same instance with `decoder.State<T>()`.
+
+### Pens and elements
+
+Text is written under the markup in force, which is built from two things:
+
+- **Pens** are named slots a protocol sets and replaces: `context.SetPen(slot, markup)`, `Pen(slot)`,
+  and `SetPen(slot, null)` to clear. SGR is a pen (`VtPens.Style`); so is a link (`VtPens.Link`).
+- **Elements** are a stack a tag protocol opens and closes: `Open(markup)`, `Close(markup)` with
+  the same instance, which also closes anything opened after it, and `CloseTo(count)`. `Open` returns
+  false at `MaxOpenElements`.
+
+Pens sit inside every element, so an SGR colour inside an element wins, as it does in an MXP client.
+
+Besides `Print`, a handler can `Write` text as it is (skipping print filters), `Write(text, inner)`
+with one more layer inside, `Point(point)`, move the cursor (`CarriageReturn`, `Backspace`,
+`MoveToColumn`), erase (`EraseToEndOfLine`, `EraseToStartOfLine`, `EraseLine`), `EndLine()`, set
+`Destination` for the lines that follow, `Raise(event)` and `Reply(text)`.
+
+### Text protocols
+
+A text protocol reads every piece of printable text while it is on, and prints what is literal with
+`context.Print`. Only one is on at a time. This one makes `*text*` bold:
+
+```csharp
+sealed class StarsPlugin : IDecoderPlugin
+{
+    public string Name => "stars";
+
+    public void Register(DecoderBuilder builder) => builder.TextProtocol("stars", () => new StarsProtocol());
+}
+
+sealed class StarsProtocol : ITextProtocol
+{
+    private readonly IMarkup _bold = AnsiMarkup.Create(bold: true);
+    private bool _open;
+
+    public void Feed(ReadOnlySpan<char> text, DecodeContext context)
+    {
+        while (true)
+        {
+            var star = text.IndexOf('*');
+            if (star < 0)
+            {
+                context.Print(text);
+                return;
+            }
+
+            context.Print(text[..star]);
+            if (_open) Close(context);
+            else _open = context.Open(_bold);
+            text = text[(star + 1)..];
+        }
+    }
+
+    public void EndLine(DecodeContext context) => Close(context);
+
+    public void Reset(DecodeContext context) => Close(context);
+
+    private void Close(DecodeContext context)
+    {
+        if (_open) context.Close(_bold);
+        _open = false;
+    }
+}
+```
+
+The registry offers the protocol; the decoder makes an instance the first time it is turned on,
+typically after telnet negotiates it:
+
+```csharp
+var decoder = DecoderRegistry.Empty.WithVt().With(new StarsPlugin()).CreateDecoder();
+decoder.EnableProtocol("stars");   // raises ProtocolEvent { Name = stars, Active = True }
+decoder.Feed("a *bold \e[31mred\e[0m bold* plain *open\n")[0].Content.Render(MarkupFormat.Ansi);
+```
+
+```
+a \e[1mbold \e[31mred\e[0m\e[1m bold\e[0m plain \e[1mopen\e[0m
+```
+
+The SGR reset inside the element ends the red pen, not the bold element. `EndLine` closed the
+element left open, so the next line starts plain. `EnableProtocol` returns false when the registry
+offers no protocol of that name; `ActiveProtocol` names the one that is on.
+
+## Pictures, MXP and Pueblo
+
+These plugins are covered in their own sections.
diff --git a/docs/display.md b/docs/display.md
new file mode 100644
index 0000000..f9518d6
--- /dev/null
+++ b/docs/display.md
@@ -0,0 +1,338 @@
+# Display
+
+A decoded line is a `MarkupText` (see [Decoding](decoding.md)). To show it, fold each run's markup
+into a `DisplayStyle` (RGB colours, attributes, what a click does) degraded to what the output can
+show. `SpanRenderer` gives runs of text for a web page; `CellRenderer` gives a grid of cells for a
+window that draws its own.
+
+```csharp
+using System.Net;
+using MarkupString;
+using MarkupString.Ansi.Decoding;
+using MarkupString.Decoding;
+using MarkupString.Display;
+
+var decoders = DecoderRegistry.Empty.WithVt();
+var display = DisplayRegistry.Core.WithAnsi();
+var options = new DisplayOptions { Capabilities = OutputCapabilities.Browser };
+
+var line = Decoder.DecodeAll("\e[1;31mDanger\e[0m: see \e]8;;https://example.com/help\e\\help\e]8;;\e\\", decoders)[0];
+
+var html = new System.Text.StringBuilder();
+foreach (var span in SpanRenderer.Render(line.Content, display, options))
+{
+    if (span.Point is not null) continue;
+    var css = SpanRenderer.Css(span.Style);
+    var classes = SpanRenderer.CssClasses(span.Style);
+    var encoded = WebUtility.HtmlEncode(span.Text);
+    if (span.Style.Interaction is { Kind: InteractionKind.Url } link)
+        html.Append($"<a href=\"{WebUtility.HtmlEncode(link.Target)}\" class=\"{classes}\">{encoded}</a>");
+    else if (css.Length == 0 && classes.Length == 0)
+        html.Append(encoded);
+    else
+        html.Append($"<span style=\"{css}\" class=\"{classes}\">{encoded}</span>");
+}
+```
+
+```html
+<span style="color:#aa0000;font-weight:bold" class="">Danger</span>: see <a href="https://example.com/help" class="ms-link">help</a>
+```
+
+`Decoder` clashes with `System.Text.Decoder`, so a file that imports `System.Text` has to qualify one
+of them.
+
+## What an output can show
+
+`OutputCapabilities` describes one output:
+
+| Property | Type | Default |
+|---|---|---|
+| `Colors` | `ColorLevel`: `None`, `Attributes`, `Standard`, `Xterm256`, `TrueColor` | `TrueColor` |
+| `Attributes` | `TextAttributes` flags: bold, faint, italic, underline, blink, inverse, conceal, strikethrough, overline | `All` |
+| `Interactions` | `InteractionKinds` flags: `Url`, `Command`, `Prompt`, `Menu` | `All` |
+| `Pictures` | `PictureMethods` flags: `Bitmap`, `KittyPlaceholders`, `InlineImages`, `Sixel`, `HalfBlocks` | `None` |
+| `MovingPictures`, `Sound`, `Panes` | `bool` | `false` |
+| `Unicode` | `UnicodeLevel`: `Full`, `Narrow`, `Ascii` | `Full` |
+
+`ColorLevel.None` means no attributes either; `Attributes` means attributes without colour.
+
+Three presets:
+
+| Preset | Differs from the defaults |
+|---|---|
+| `PlainText` | No colours, no attributes, no interactions |
+| `Browser` | `Bitmap` pictures, moving pictures, sound, panes |
+| `CellGrid` | `Bitmap` and `HalfBlocks` pictures, moving pictures, sound, panes |
+
+Change one with `with`:
+
+```csharp
+var capabilities = OutputCapabilities.Browser with { Colors = ColorLevel.Xterm256, Attributes = TextAttributes.All & ~TextAttributes.Blink };
+```
+
+A terminal's capabilities come from its `TerminalProfile` and the colour depth you settled on:
+
+```csharp
+var terminal = TerminalProfile.Kitty.ToOutputCapabilities(AnsiColorDepth.Xterm256);
+// Colors = Xterm256, Interactions = Url, Pictures = KittyPlaceholders, HalfBlocks, MovingPictures = True
+```
+
+`ToOutputCapabilities` sets `Url` from `Hyperlinks`, `Command` from `CommandLinks`, and pictures from
+`KittyGraphics`, `InlineImages`, `Sixel` and `BlockArt`. It never sets sound or panes.
+
+`Intersect` gives what both outputs can show: the lesser colour and Unicode level, and the shared
+flags. `Union` gives what either can, for a client that shows one session in two places and tells
+the server once.
+
+```csharp
+var both = OutputCapabilities.Browser.Intersect(terminal);    // Xterm256, Url, no pictures, no sound
+var either = OutputCapabilities.Browser.Union(terminal);      // TrueColor, All, Bitmap | KittyPlaceholders | HalfBlocks, sound
+```
+
+`BestPictureMethod` is the first of `Bitmap`, `KittyPlaceholders`, `InlineImages`, `Sixel`,
+`HalfBlocks` that the output has.
+
+## The display registry
+
+A `DisplayRegistry` is the list of `IStyleContributor`s that fold markup into a style. Build it once
+and share it.
+
+| Registry | Knows |
+|---|---|
+| `DisplayRegistry.Empty` | Nothing: every run is plain |
+| `DisplayRegistry.Core` | The shared vocabulary (`VocabularyStyles`): `ImageMarkup`, `PaneMarkup`, `CommandMenuMarkup`, `HighlightMarkup` |
+| `Core.WithAnsi()` | Also `AnsiStyles`: every layer that is an `IAnsiStyleSource` (SGR, an MXP colour, an HTML `<b>`) |
+| `AnsiDisplay.Default` | The same as `Core.WithAnsi()` |
+
+`WithAnsi(boldIsBright: true)` draws bold text in a standard colour in its bright version, as many
+MUD clients do: `\e[1;31m` becomes `#ff5555` instead of `#aa0000`.
+
+Contributors run in the order they were added, each writing into one `StyleBuilder`. Within a
+contributor the innermost layer has the last word. `AnsiStyles` sets the foreground and attributes,
+but leaves a background or interaction an earlier contributor set, so a `HighlightMarkup` over SGR
+text keeps its background and a command menu keeps its menu.
+
+A contributor of your own reads the layers it knows and leaves the rest:
+
+```csharp
+sealed class ChatColor : IStyleContributor
+{
+    public void Contribute(MarkupSet markups, StyleBuilder style, DisplayOptions options)
+    {
+        foreach (var markup in markups)
+        {
+            if (markup is PaneMarkup { Name: "chat" }) style.Foreground ??= new RgbColor(150, 200, 255);
+        }
+    }
+}
+
+var display = DisplayRegistry.Core.WithAnsi().With(new ChatColor());
+```
+
+Added last with `??=`, it colours chat text only where the server gave no colour.
+
+`display.Resolve(markups, options)` folds one `MarkupSet` and degrades it. The renderers call it once
+per markup set in a text.
+
+## Options
+
+`DisplayOptions`:
+
+| Property | Default | |
+|---|---|---|
+| `Capabilities` | `Browser` | What the output can show |
+| `Colors` | null | An `IColorResolver`; null uses the xterm palette |
+| `DefaultForeground` | `(229, 229, 229)` | Used when inverse text has no colour of its own |
+| `DefaultBackground` | `(0, 0, 0)` | Used when inverse text has no background of its own |
+| `TabWidth` | 8 | Cells between tab stops, in `CellRenderer` |
+
+An `IColorResolver` decides what "red" is. Subclass `AnsiColors` to change part of the palette:
+
+```csharp
+sealed class Theme : AnsiColors
+{
+    public override RgbColor Standard(int index, bool bright) =>
+        index == 1 && !bright ? new RgbColor(220, 50, 47) : base.Standard(index, bright);
+
+    // Keep text readable when the server paints it on its own colour.
+    public override RgbColor Legible(RgbColor foreground, RgbColor background) =>
+        foreground == background ? new RgbColor(255, 255, 255) : foreground;
+}
+
+var themed = new DisplayOptions { Colors = new Theme() };
+var text = Decoder.DecodeAll("\e[31mred\e[0m \e[34;44msame\e[0m", decoders)[0].Content;
+```
+
+```
+"red"  color:#dc322f
+" "
+"same" color:#ffffff;background-color:#0000aa
+```
+
+`Legible` is called only when `Colors` is set, with the final foreground and the background
+(`DefaultBackground` when there is none).
+
+## Degrading
+
+`Resolve` drops what the output cannot show, in this order:
+
+- **Colours.** At `ColorLevel.Attributes` or `None` both colours are dropped. Above that, every colour
+  is already RGB, so the level does not reduce it further here.
+- **Attributes.** Those the output lacks are dropped. At `ColorLevel.None` every attribute is.
+- **Inverse.** With colour, foreground and background are swapped, filling in `DefaultForeground` and
+  `DefaultBackground`; `Inverse` stays set for information. At `Attributes` the flag is kept for the
+  output to draw when it has `TextAttributes.Inverse`, and dropped when it does not.
+- **Interactions.** Menu choices go when the output has no `Menu`. A prompt link becomes a command
+  link on an output with `Command` but not `Prompt`. Any other interaction the output lacks is dropped,
+  and the text stays.
+- **Pictures** are dropped when `Pictures` is `None`, leaving the picture's text.
+- **Panes** are dropped when `Panes` is false, so the text shows in the main output.
+
+The renderers also fold text with `AsciiFold` at `UnicodeLevel.Ascii`, draw a wide character as `?`
+in cells at `Narrow`, and drop sound points (`SoundMarkup`, `SoundStopMarkup`) when `Sound` is false.
+Other points, such as a bell, are kept.
+
+The same line for three outputs:
+
+```csharp
+var sample = Decoder.DecodeAll("\e[1;31mred\e[0m \e[7minverse\e[0m", decoders)[0].Content;
+SpanRenderer.Render(sample, display, new DisplayOptions { Capabilities = OutputCapabilities.Browser });
+```
+
+| Capabilities | Spans |
+|---|---|
+| `Browser` | `"red"` #aa0000, bold · `" "` · `"inverse"` #000000 on #e5e5e5, inverse |
+| `Browser with { Colors = ColorLevel.Attributes }` | `"red"` bold · `" "` · `"inverse"` inverse, no colours |
+| `PlainText` | `"red inverse"` |
+
+A command menu on a browser, and on an output with commands but no menus:
+
+```csharp
+var menu = MarkupText.Wrap(new CommandMenuMarkup([new("Look", "look sword"), new("Take", "take sword")], "A sword"), "sword");
+
+display.Resolve(menu.Runs[0].Markups, options).Interaction;
+// Kind = Command, Target = look sword, Choices: 2
+
+display.Resolve(menu.Runs[0].Markups, new DisplayOptions
+{
+    Capabilities = OutputCapabilities.Browser with { Interactions = InteractionKinds.Command },
+}).Interaction;
+// Kind = Command, Target = look sword, Choices: null
+```
+
+## Spans
+
+`SpanRenderer.Render(text, registry, options)` returns `DisplaySpan`s in order. Adjacent text with
+the same style is one span. A point (a bell, a sound, a clear) is a span of its own with empty `Text`
+and `Point` set. Text no markup covers is `DisplayStyle.Plain`.
+
+`SpanRenderer.Css(style)` is inline CSS: `color`, `background-color`, `font-weight:bold`,
+`opacity:0.6` for faint, `font-style:italic`, `text-decoration` for underline, overline and
+line-through, and `color:transparent` for conceal. `CssClasses(style)` gives the classes a page
+styles itself:
+
+| Class | When |
+|---|---|
+| `ms-blink` | Blink, which CSS has no property for |
+| `ms-conceal` | Conceal |
+| `ms-link`, `ms-command`, `ms-prompt` | The interaction's kind |
+| `ms-menu` | An interaction with more than one choice |
+| `ms-picture` | A picture |
+
+`SpanRenderer.Hex(color)` writes `#rrggbb`.
+
+## Cells
+
+`CellRenderer.Layout(text, columns, registry, options, wordWrap)` lays text on a grid for an output
+that draws cells itself.
+
+```csharp
+var grid = new DisplayOptions { Capabilities = OutputCapabilities.CellGrid };
+var text = Decoder.DecodeAll("Go \e]8;;https://example.com\e\\north\e]8;;\e\\ to the 漢字 gate", decoders)[0].Content;
+
+var layout = CellRenderer.Layout(text, 12, display, grid, wordWrap: true);
+foreach (var row in layout.Rows)
+{
+    var shown = string.Concat(row.Cells.Select(cell => cell.Text));
+    Console.WriteLine($"|{shown}| {row.Cells.Count} cells{(row.Wrapped ? ", wrapped" : "")}");
+}
+```
+
+```
+|Go north to | 12 cells, wrapped
+|the 漢字 | 9 cells, wrapped
+|gate| 4 cells
+```
+
+- `columns` is the width to wrap at; 0 does not wrap. A line feed in the text starts a new row.
+- Without `wordWrap` a row breaks at the last cell. With it, a row breaks after the last space that
+  fits, and the space stays at the end of the row. A word with no space before it on the row breaks
+  at the last cell.
+- A row is as long as its text and is never padded. `Wrapped` says the next row continues it.
+- A tab advances to the next multiple of `TabWidth`, never past `columns`, and its cells take the
+  style of its run.
+- A wide character takes two cells: the second is a continuation, with empty `Text` and `Width` 0
+  (`IsContinuation`). A wide character that does not fit in the last column moves to the next row.
+- A combining mark joins the cell before it.
+
+`layout.At(row, column)` is the cell there, or null past the text. `InteractionAt(row, column)` is
+what clicking it does; the right half of a wide character answers for the whole.
+
+```csharp
+layout.InteractionAt(0, 4)?.Target;   // https://example.com
+layout.InteractionAt(0, 1)?.Target;   // null
+layout.At(1, 7);                      // the continuation of 字: Text "", Width 0
+```
+
+Points are listed apart, in `layout.Points`, each with the row and column it stands before.
+
+### Pictures
+
+A picture laid out over rows of cells (an `ImageMarkup` with a `Row`) has blank cells, each with
+`Style.Picture` set. `Cell.PictureColumn` is the cell's column within the picture, from its left
+edge, or from `PictureRow.FirstColumn` for a cropped placement. With `Picture.Row.Row` it says which
+part of the picture to draw in that cell.
+
+```csharp
+var picture = new ImageMarkup("map.png", "A map") { Row = new PictureRow(0, 3, 6) };
+var row = MarkupText.Concat([MarkupText.Plain("> "), MarkupText.Wrap(picture, "      ")]);
+CellRenderer.Layout(row, 0, display, grid).Rows[0].Cells.Select(c => c.Style.Picture is null ? "." : c.PictureColumn.ToString());
+// . . 0 1 2 3 4 5
+```
+
+Word wrap never breaks at a space inside a picture.
+
+## Back to ANSI
+
+A terminal output takes the decoded line as it is, through `Render(MarkupFormat.Ansi)` with a
+registry for that client. `ToColorDepth` and `ToTerminalFeatures` turn capabilities into what
+`AnsiOutputOptions` takes:
+
+```csharp
+var caps = OutputCapabilities.Browser with { Colors = ColorLevel.Standard, Interactions = InteractionKinds.None };
+var ansi = MarkupRegistry.Empty.WithAnsi().WithAnsiOutput(new AnsiOutputOptions(caps.ToColorDepth(), caps.ToTerminalFeatures()));
+
+var rich = Decoder.DecodeAll("\e[38;2;255;100;0morange\e[0m \e]8;;https://example.com\e\\link\e]8;;\e\\", decoders)[0].Content;
+rich.Render(MarkupFormat.Ansi, MarkupRegistry.Empty.WithAnsi());   // \e[38;2;255;100;0morange\e[0m \e]8;;https://example.com\alink\e]8;;\a
+rich.Render(MarkupFormat.Ansi, ansi);                              // \e[1;31morange\e[0m link
+```
+
+At `Standard` the orange became the nearest standard colour, bright red, written as bold red; with no
+`Url` interaction the link is its text.
+
+## Telling the server
+
+The capabilities you render with are also what the client tells the server it accepts. Put them in
+the decoder's identity, so answers and MTTS match what is drawn:
+
+```csharp
+var window = OutputCapabilities.CellGrid;
+var logView = OutputCapabilities.Browser with { Colors = ColorLevel.Xterm256 };
+
+var identity = new ClientIdentity { Output = window.Union(logView) };
+identity.ToMtts();   // Ansi, Vt100, Utf8, Colors256, OscColorPalette, TrueColor, Mslp
+```
+
+Use `Union` when one session is shown in two places and the server is told once; render each place
+with its own capabilities, so each drops what it cannot show. `ToMtts` is covered in
+[Decoding](decoding.md#mtts).

From 788f716d3c81722ad77153358d75006655000b66 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 21:59:18 +0000
Subject: [PATCH 08/19] Break over-long lines, blank split wide characters, end
 MSLP links at the line, prompt menus, inverse class; add decoding and display
 docs

---
 MarkupString.Ansi/Decoding/VtPlugins.cs       |  9 +++++
 MarkupString.Tests/Ansi/AnsiCssTests.cs       |  1 +
 MarkupString.Tests/Decoding/DisplayTests.cs   | 17 +++++++++
 .../Decoding/VtDecodingTests.cs               | 26 ++++++++++---
 MarkupString/Decoding/DecodeContext.cs        | 15 +++++++-
 MarkupString/Decoding/DecoderRegistry.cs      |  2 +-
 MarkupString/Decoding/LineBuilder.cs          | 38 +++++++++++++++++--
 MarkupString/Display/DisplayRegistry.cs       |  2 +-
 MarkupString/Display/DisplayStyle.cs          |  2 +-
 MarkupString/Display/SpanRenderer.cs          |  6 ++-
 10 files changed, 103 insertions(+), 15 deletions(-)

diff --git a/MarkupString.Ansi/Decoding/VtPlugins.cs b/MarkupString.Ansi/Decoding/VtPlugins.cs
index 3bb4a80..02ccd8c 100644
--- a/MarkupString.Ansi/Decoding/VtPlugins.cs
+++ b/MarkupString.Ansi/Decoding/VtPlugins.cs
@@ -393,6 +393,15 @@ public void Register(DecoderBuilder builder)
 				context.State<VtState>().MslpUnderlined = false;
 				return true;
 			})
+			.OnLineEnd(static context =>
+			{
+				// An MSLP link is on one line; an OSC 8 link lasts until it is ended.
+				if (context.Pen(VtPens.Link) is AnsiMarkup { Style.LinkKind: LinkKind.Command })
+				{
+					context.SetPen(VtPens.Link, null);
+					context.State<VtState>().MslpUnderlined = false;
+				}
+			})
 			.OnOsc(0, static (payload, context) => Title(payload, context, icon: true))
 			.OnOsc(1, static (payload, context) => Title(payload, context, icon: true))
 			.OnOsc(2, static (payload, context) => Title(payload, context, icon: false))
diff --git a/MarkupString.Tests/Ansi/AnsiCssTests.cs b/MarkupString.Tests/Ansi/AnsiCssTests.cs
index 93a1167..7cecfa8 100644
--- a/MarkupString.Tests/Ansi/AnsiCssTests.cs
+++ b/MarkupString.Tests/Ansi/AnsiCssTests.cs
@@ -23,6 +23,7 @@ public class AnsiCssTests
 		AnsiStyle.None with { Overlined = true },
 		AnsiStyle.None with { Blink = true },
 		AnsiStyle.None with { Inverted = true },
+		AnsiStyle.None with { Concealed = true },
 	];
 
 	[Test]
diff --git a/MarkupString.Tests/Decoding/DisplayTests.cs b/MarkupString.Tests/Decoding/DisplayTests.cs
index 13fbacc..8b1082f 100644
--- a/MarkupString.Tests/Decoding/DisplayTests.cs
+++ b/MarkupString.Tests/Decoding/DisplayTests.cs
@@ -66,6 +66,23 @@ public async Task BoldIsBright()
 		await Assert.That(style.Foreground).IsEqualTo(new RgbColor(255, 85, 85));
 	}
 
+	[Test]
+	public async Task Resolve_PromptMenu_IsAPrompt()
+	{
+		var menu = new CommandMenuMarkup([new CommandChoice("Say", "say ")], Prompt: true);
+		var style = AnsiDisplay.Default.Resolve(MarkupSet.Of(menu), Browser);
+		await Assert.That(style.Interaction!.Kind).IsEqualTo(InteractionKind.Prompt);
+		await Assert.That(SpanRenderer.CssClasses(style)).IsEqualTo("ms-prompt");
+	}
+
+	[Test]
+	public async Task Inverse_WithoutColours_IsAClass()
+	{
+		var options = new DisplayOptions { Capabilities = OutputCapabilities.Browser with { Colors = ColorLevel.Attributes } };
+		var style = AnsiDisplay.Default.Resolve(MarkupSet.Of(AnsiMarkup.Create(inverted: true)), options);
+		await Assert.That(SpanRenderer.CssClasses(style)).IsEqualTo("ms-invert");
+	}
+
 	[Test]
 	public async Task Spans_MergeEqualStyles()
 	{
diff --git a/MarkupString.Tests/Decoding/VtDecodingTests.cs b/MarkupString.Tests/Decoding/VtDecodingTests.cs
index ad5699e..08d7256 100644
--- a/MarkupString.Tests/Decoding/VtDecodingTests.cs
+++ b/MarkupString.Tests/Decoding/VtDecodingTests.cs
@@ -284,13 +284,29 @@ public async Task Unknown_IsCounted()
 	}
 
 	[Test]
-	public async Task LineLength_IsCapped()
+	public async Task LineLength_BreaksTheLine()
 	{
 		var decoder = VtDecoding.Terminal.CreateDecoder(new DecoderOptions { MaxLineLength = 4 });
-		decoder.Feed("abc");
-		decoder.Feed("def");
-		await Assert.That(decoder.EndLine().Content.ToPlainText()).IsEqualTo("abc");
-		await Assert.That(decoder.Diagnostics.LimitsReached).IsEqualTo(1);
+		var lines = new List<DisplayLine>(decoder.Feed("abc"));
+		lines.AddRange(decoder.Feed("defghij\n"));
+		await Assert.That(lines.Select(line => line.Content.ToPlainText())).IsEquivalentTo(["abcd", "efgh", "ij"]);
+		await Assert.That(decoder.Diagnostics.LimitsReached).IsEqualTo(2);
+	}
+
+	[Test]
+	public async Task Overwrite_InsideAWideCharacter_BlanksIt()
+	{
+		await Assert.That(Decode("漢字\rX\n")[0].Content.ToPlainText()).IsEqualTo("X 字");
+		await Assert.That(Decode("漢字\e[2GX\n")[0].Content.ToPlainText()).IsEqualTo(" X字");
+		await Assert.That(Decode("ab漢\e[2G字\n")[0].Content.ToPlainText()).IsEqualTo("a字 ");
+	}
+
+	[Test]
+	public async Task Mslp_WithoutUnderline_EndsWithTheLine()
+	{
+		var lines = Decode("\e]68;1;SEND;look\alook\nmore\n");
+		await Assert.That(Spans(lines[0].Content).Single().Style.Interaction).IsNotNull();
+		await Assert.That(Spans(lines[1].Content).Single().Style.Interaction).IsNull();
 	}
 
 	[Test]
diff --git a/MarkupString/Decoding/DecodeContext.cs b/MarkupString/Decoding/DecodeContext.cs
index da13ab2..800b851 100644
--- a/MarkupString/Decoding/DecodeContext.cs
+++ b/MarkupString/Decoding/DecodeContext.cs
@@ -200,7 +200,20 @@ public void Write(ReadOnlySpan<char> text, IMarkup? inner)
 				set = MarkupSet.Of(layers.AsSpan());
 			}
 		}
-		if (!Line.Write(text.ToString(), set)) Diagnostics.LimitsReached++;
+		// A line too long for the limit is ended where the limit falls, and the rest starts the next.
+		while (Line.Length + text.Length > Line.MaxLength)
+		{
+			var room = Math.Max(0, Line.MaxLength - Line.Length);
+			if (room > 0 && char.IsHighSurrogate(text[room - 1])) room--;
+			if (room == 0 && Line.IsEmpty) room = Math.Min(text.Length, Math.Max(1, Line.MaxLength));
+			if (room > 0) Line.Write(text[..room].ToString(), set);
+			Diagnostics.LimitsReached++;
+			EndLine();
+			text = text[room..];
+			if (text.IsEmpty) return;
+		}
+
+		Line.Write(text.ToString(), set);
 	}
 
 	/// <summary>Writes already built text at the cursor.</summary>
diff --git a/MarkupString/Decoding/DecoderRegistry.cs b/MarkupString/Decoding/DecoderRegistry.cs
index 80def85..1c826a8 100644
--- a/MarkupString/Decoding/DecoderRegistry.cs
+++ b/MarkupString/Decoding/DecoderRegistry.cs
@@ -224,6 +224,6 @@ public sealed record DecoderOptions
 	/// <summary>The most elements a text protocol may have open at once.</summary>
 	public int MaxOpenElements { get; init; } = 64;
 
-	/// <summary>The longest line, in characters; longer lines are broken.</summary>
+	/// <summary>The longest line, in characters; a longer line is ended there and the rest starts a new one.</summary>
 	public int MaxLineLength { get; init; } = 64 * 1024;
 }
diff --git a/MarkupString/Decoding/LineBuilder.cs b/MarkupString/Decoding/LineBuilder.cs
index 07a2b90..b2be130 100644
--- a/MarkupString/Decoding/LineBuilder.cs
+++ b/MarkupString/Decoding/LineBuilder.cs
@@ -13,6 +13,12 @@ internal sealed class LineBuilder(int maxLength)
 
 	public bool IsEmpty => _parts.Count == 0;
 
+	/// <summary>The characters on the line.</summary>
+	public int Length => _length;
+
+	/// <summary>The longest the line may be.</summary>
+	public int MaxLength => maxLength;
+
 	/// <summary>The column the next text is written at. Past the end, the gap is filled with spaces when text comes.</summary>
 	public int Cursor
 	{
@@ -43,12 +49,36 @@ public bool Put(MarkupText text)
 			return true;
 		}
 
-		// Overwrite the cells from the cursor on.
+		// Overwrite the cells from the cursor on. A wide character the cursor lands inside, or that the new text
+		// only partly covers, is blanked where it is not covered, as a terminal blanks it.
 		var line = Materialise();
 		var before = line.Substring(0, DisplayWidth.IndexAtWidth(line.Text, _cursor));
-		var after = line.Substring(DisplayWidth.IndexAtWidth(line.Text, _cursor + width));
-		Replace(MarkupText.Concat([before, text, after]));
-		_cursor = before.DisplayWidth + width;
+		var leading = _cursor - before.DisplayWidth;
+
+		var end = _cursor + width;
+		var afterIndex = DisplayWidth.IndexAtWidth(line.Text, end);
+		var reached = DisplayWidth.Of(line.Text.AsSpan(0, afterIndex));
+		if (reached < end && afterIndex < line.Length)
+		{
+			var span = line.Text.AsSpan(afterIndex);
+			var enumerator = Graphemes.Enumerate(span);
+			if (enumerator.MoveNext())
+			{
+				var cluster = enumerator.Current.End.GetOffset(span.Length);
+				reached += DisplayWidth.Of(span[..cluster]);
+				afterIndex += cluster;
+			}
+		}
+
+		var trailing = Math.Max(0, reached - end);
+		var after = line.Substring(afterIndex);
+		Replace(MarkupText.Concat([
+			before,
+			leading > 0 ? MarkupText.Plain(new string(' ', leading)) : MarkupText.Empty,
+			text,
+			trailing > 0 ? MarkupText.Plain(new string(' ', trailing)) : MarkupText.Empty,
+			after]));
+		_cursor = end;
 		return true;
 	}
 
diff --git a/MarkupString/Display/DisplayRegistry.cs b/MarkupString/Display/DisplayRegistry.cs
index ed7b51b..d29e925 100644
--- a/MarkupString/Display/DisplayRegistry.cs
+++ b/MarkupString/Display/DisplayRegistry.cs
@@ -132,7 +132,7 @@ public void Contribute(MarkupSet markups, StyleBuilder style, DisplayOptions opt
 					style.Pane = pane.Name;
 					break;
 				case CommandMenuMarkup menu when menu.Choices.Count > 0:
-					style.Interaction = new Interaction(InteractionKind.Command, menu.Choices[0].Command)
+					style.Interaction = new Interaction(menu.Prompt ? InteractionKind.Prompt : InteractionKind.Command, menu.Choices[0].Command)
 					{
 						Hint = menu.Hint,
 						Choices = menu.Choices,
diff --git a/MarkupString/Display/DisplayStyle.cs b/MarkupString/Display/DisplayStyle.cs
index 0f14687..fe78269 100644
--- a/MarkupString/Display/DisplayStyle.cs
+++ b/MarkupString/Display/DisplayStyle.cs
@@ -25,7 +25,7 @@ public sealed record Interaction(InteractionKind Kind, string Target)
 	public IReadOnlyList<CommandChoice>? Choices { get; init; }
 
 	/// <summary>
-	/// Text with the same group is one link for hover and focus, even across lines (an OSC 8 <c>id</c>). Null groups
+	/// Text with the same group is one link for hover and focus, even across lines (as an OSC 8 <c>id</c> groups them), as a contributor sets it. Null groups
 	/// by <see cref="Target"/> alone.
 	/// </summary>
 	public string? Group { get; init; }
diff --git a/MarkupString/Display/SpanRenderer.cs b/MarkupString/Display/SpanRenderer.cs
index f34a79e..060548b 100644
--- a/MarkupString/Display/SpanRenderer.cs
+++ b/MarkupString/Display/SpanRenderer.cs
@@ -66,7 +66,7 @@ public static IReadOnlyList<DisplaySpan> Render(MarkupText text, DisplayRegistry
 	public static string Css(DisplayStyle style)
 	{
 		var css = new StringBuilder();
-		if (style.Foreground is { } foreground) Append(css, "color", Hex(foreground));
+		if (style.Foreground is { } foreground && !style.Has(TextAttributes.Conceal)) Append(css, "color", Hex(foreground));
 		if (style.Background is { } background) Append(css, "background-color", Hex(background));
 		if (style.Has(TextAttributes.Bold)) Append(css, "font-weight", "bold");
 		if (style.Has(TextAttributes.Faint)) Append(css, "opacity", "0.6");
@@ -84,13 +84,15 @@ public static string Css(DisplayStyle style)
 
 	/// <summary>
 	/// The class names a page styles itself: <c>ms-blink</c>, <c>ms-conceal</c>, <c>ms-link</c>, <c>ms-command</c>,
-	/// <c>ms-prompt</c>, <c>ms-menu</c> and <c>ms-picture</c>. Empty for plain text.
+	/// <c>ms-prompt</c>, <c>ms-menu</c>, <c>ms-picture</c>, and <c>ms-invert</c> for inverse text with no colours of its own to
+	/// swap (an output that shows attributes but no colour). Empty for plain text.
 	/// </summary>
 	public static string CssClasses(DisplayStyle style)
 	{
 		var classes = new List<string>(3);
 		if (style.Has(TextAttributes.Blink)) classes.Add("ms-blink");
 		if (style.Has(TextAttributes.Conceal)) classes.Add("ms-conceal");
+		if (style.Has(TextAttributes.Inverse) && style.Foreground is null && style.Background is null) classes.Add("ms-invert");
 		if (style.Interaction is { } interaction)
 		{
 			classes.Add(interaction.Kind switch

From 390ff5a07dcc2d67eb0583e48ee5c6753b2cec4d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 22:05:07 +0000
Subject: [PATCH 09/19] Decode MXP: line modes, tags, entities, custom
 elements, menus, answers

---
 MarkupString.Mxp/Decoding/MxpDecoding.cs      | 811 ++++++++++++++++++
 MarkupString.Mxp/MarkupString.Mxp.csproj      |   1 +
 MarkupString.Mxp/PublicAPI.Unshipped.txt      |  25 +
 .../Decoding/MxpDecodingTests.cs              | 237 +++++
 MarkupString/Decoding/TagScanner.cs           | 187 ++++
 MarkupString/Decoding/TagSyntax.cs            | 181 ++++
 MarkupString/PublicAPI.Unshipped.txt          |  53 ++
 7 files changed, 1495 insertions(+)
 create mode 100644 MarkupString.Mxp/Decoding/MxpDecoding.cs
 create mode 100644 MarkupString.Tests/Decoding/MxpDecodingTests.cs
 create mode 100644 MarkupString/Decoding/TagScanner.cs
 create mode 100644 MarkupString/Decoding/TagSyntax.cs

diff --git a/MarkupString.Mxp/Decoding/MxpDecoding.cs b/MarkupString.Mxp/Decoding/MxpDecoding.cs
new file mode 100644
index 0000000..a38e74a
--- /dev/null
+++ b/MarkupString.Mxp/Decoding/MxpDecoding.cs
@@ -0,0 +1,811 @@
+using System.Globalization;
+using System.Text;
+using System.Text.Json;
+using MarkupString.Ansi;
+using MarkupString.Decoding;
+namespace MarkupString.Mxp.Decoding;
+
+/// <summary>
+/// Says what an MXP line tag or a <c>FLAG</c> marks the text as: a room's name, its description, its exits, or
+/// whatever a server's own element flags. It changes nothing about how the text looks.
+/// </summary>
+/// <param name="Flag">The flag, as the server named it, such as <c>RoomName</c>.</param>
+public sealed record MxpFlagMarkup(string Flag) : IDataMarkup
+{
+	/// <summary>A room's name (line tag 10).</summary>
+	public const string RoomName = "RoomName";
+
+	/// <summary>A room's description (line tag 11).</summary>
+	public const string RoomDescription = "RoomDesc";
+
+	/// <summary>A room's exits (line tag 12).</summary>
+	public const string RoomExits = "RoomExit";
+
+	/// <summary>The welcome text (line tag 19).</summary>
+	public const string Welcome = "Welcome";
+}
+
+/// <summary>Registers MXP decoding on a <see cref="DecoderRegistry"/>.</summary>
+public static class MxpDecoding
+{
+	/// <summary>The name to pass <see cref="MarkupString.Decoding.Decoder.EnableProtocol(string)"/> once telnet has negotiated MXP.</summary>
+	public const string Protocol = "mxp";
+
+	/// <summary>The registry with <see cref="MxpPlugin"/>.</summary>
+	public static DecoderRegistry WithMxp(this DecoderRegistry registry)
+	{
+		ArgumentNullException.ThrowIfNull(registry);
+		return registry.With(MxpPlugin.Instance);
+	}
+
+	/// <summary>The codec that stores <see cref="MxpFlagMarkup"/>, for a registry that serialises decoded lines.</summary>
+	public static IMarkupCodec FlagCodec { get; } = new MxpFlagCodec();
+
+	private sealed class MxpFlagCodec : IMarkupCodec
+	{
+		public string Kind => "mxp-flag";
+
+		public Type MarkupType => typeof(MxpFlagMarkup);
+
+		public void Write(Utf8JsonWriter writer, IMarkup markup) => writer.WriteString("f", ((MxpFlagMarkup)markup).Flag);
+
+		public IMarkup Read(JsonElement element) =>
+			new MxpFlagMarkup(element.TryGetProperty("f", out var flag) && flag.ValueKind == JsonValueKind.String ? flag.GetString()! : string.Empty);
+	}
+}
+
+/// <summary>
+/// MXP, the MUD eXtension Protocol, as a text protocol: tags and entities in the text, and the line modes
+/// (<c>ESC [ n z</c>) that say which tags a line may use. Turn it on with
+/// <see cref="MarkupString.Decoding.Decoder.EnableProtocol(string)"/>(<see cref="MxpDecoding.Protocol"/>) when telnet negotiates it.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Styles (<c>B</c>, <c>I</c>, <c>U</c>, <c>S</c>, <c>H</c>, <c>COLOR</c>, <c>FONT</c>) become <see cref="AnsiMarkup"/>; links
+/// (<c>A</c>, <c>SEND</c>) a link on an <see cref="AnsiMarkup"/>, with a <see cref="CommandMenuMarkup"/> for a menu or a
+/// prompt; <c>IMAGE</c>, <c>SOUND</c>, <c>MUSIC</c>, <c>DEST</c>, <c>EXPIRE</c>, <c>RELOCATE</c>, <c>USER</c>,
+/// <c>PASSWORD</c> and <c>VAR</c> the shared vocabulary; and custom elements (<c>&lt;!ELEMENT&gt;</c>) what their
+/// definitions say. <c>VERSION</c> and <c>SUPPORT</c> are answered from the decoder's identity.
+/// </para>
+/// <para>
+/// A secure tag on a line that is not secure is dropped, as the protocol says, and counted as unhandled.
+/// </para>
+/// </remarks>
+public sealed class MxpPlugin : IDecoderPlugin
+{
+	/// <summary>The one instance.</summary>
+	public static MxpPlugin Instance { get; } = new();
+
+	/// <summary>The tags this decoder reads, as <c>&lt;SUPPORTS&gt;</c> answers.</summary>
+	public static IReadOnlyList<string> Supported { get; } =
+	[
+		"B", "BOLD", "STRONG", "I", "ITALIC", "EM", "U", "UNDERLINE", "S", "STRIKEOUT", "H", "HIGH", "C", "COLOR", "FONT",
+		"BR", "SBR", "P", "NOBR", "A", "SEND", "EXPIRE", "VERSION", "SUPPORT", "IMAGE", "SOUND", "MUSIC", "FRAME", "DEST",
+		"RELOCATE", "USER", "PASSWORD", "VAR", "ELEMENT", "ENTITY", "ATTLIST", "TAG",
+	];
+
+	private MxpPlugin()
+	{
+	}
+
+	/// <inheritdoc/>
+	public string Name => "mxp";
+
+	/// <inheritdoc/>
+	public void Register(DecoderBuilder builder)
+	{
+		ArgumentNullException.ThrowIfNull(builder);
+		builder
+			.TextProtocol(MxpDecoding.Protocol, static () => new MxpReader())
+			.OnCsi('z', static (in CsiSequence sequence, DecodeContext context) =>
+			{
+				// A line mode means nothing until MXP is on, and is dropped.
+				if (context.IsActive(MxpDecoding.Protocol)) MxpReader.LineMode(sequence.Get(0), context);
+				return true;
+			});
+	}
+}
+
+internal enum MxpMode
+{
+	Open,
+	Secure,
+	Locked,
+}
+
+internal sealed record MxpElementDefinition(string Name, string Definition, IReadOnlyList<TagArgument> Attributes, string? Flag, bool Open, bool Empty);
+
+internal sealed class MxpOpenElement(string name, IMarkup? first, bool openMode, bool lineTag)
+{
+	public string Name { get; } = name;
+
+	public IMarkup? First { get; } = first;
+
+	public bool OpenMode { get; } = openMode;
+
+	public bool LineTag { get; } = lineTag;
+}
+
+internal sealed class MxpState
+{
+	public MxpMode Default { get; set; } = MxpMode.Open;
+
+	public MxpMode Line { get; set; } = MxpMode.Open;
+
+	public bool TemporarySecure { get; set; }
+
+	public bool InBreak { get; set; }
+
+	public List<MxpOpenElement> Open { get; } = [];
+
+	public Dictionary<string, MxpElementDefinition> Elements { get; } = new(StringComparer.OrdinalIgnoreCase);
+
+	public Dictionary<string, string> Entities { get; } = new(StringComparer.OrdinalIgnoreCase);
+
+	public Dictionary<int, string> LineTags { get; } = [];
+
+	public Dictionary<string, string?> FrameTitles { get; } = new(StringComparer.OrdinalIgnoreCase);
+
+	public ParsedTag? Capture { get; set; }
+
+	public StringBuilder CaptureRaw { get; } = new();
+
+	public StringBuilder CaptureText { get; } = new();
+
+	public int CaptureDepth { get; set; }
+
+	public List<(ImageMarkup Image, int Rows, int Columns, int Column, int Next)> Overlays { get; } = [];
+}
+
+internal sealed class MxpReader : ITextProtocol, ITagSink
+{
+	private const int MaxCapture = 4096;
+
+	private static readonly HashSet<string> OpenTags = new(StringComparer.OrdinalIgnoreCase)
+	{
+		"B", "BOLD", "STRONG", "I", "ITALIC", "EM", "U", "UNDERLINE", "S", "STRIKEOUT", "STRIKE", "H", "HIGH", "C", "COLOR",
+		"FONT", "NOBR", "P", "BR", "SBR", "SMALL", "TT",
+	};
+
+	private readonly TagScanner _scanner = new();
+	private DecodeContext? _context;
+
+	private DecodeContext Context => _context!;
+
+	private MxpState State => Context.State<MxpState>();
+
+	public bool ReadsMarkup
+	{
+		get
+		{
+			var state = State;
+			return state.TemporarySecure || state.Line != MxpMode.Locked;
+		}
+	}
+
+	private bool Secure
+	{
+		get
+		{
+			var state = State;
+			return state.TemporarySecure || state.Line == MxpMode.Secure;
+		}
+	}
+
+	public void Feed(ReadOnlySpan<char> text, DecodeContext context)
+	{
+		_context = context;
+		_scanner.Feed(text, this);
+	}
+
+	public void EndLine(DecodeContext context)
+	{
+		_context = context;
+		var state = State;
+		_scanner.Flush(this);
+		if (state.Capture is not null) FinishCapture();
+		DrawOverlays();
+		if (state.InBreak) return;
+
+		// Elements opened on an open line, and line tags, end with it.
+		var index = state.Open.FindIndex(element => element.OpenMode || element.LineTag);
+		if (index >= 0) CloseFrom(index);
+		state.Line = state.Default;
+		state.TemporarySecure = false;
+	}
+
+	public void Reset(DecodeContext context)
+	{
+		_context = context;
+		_scanner.Reset();
+		var state = State;
+		if (state.Open.Count > 0) CloseFrom(0);
+		state.Capture = null;
+		state.Overlays.Clear();
+		state.Line = state.Default = MxpMode.Open;
+		state.TemporarySecure = false;
+	}
+
+	internal static void LineMode(int mode, DecodeContext context)
+	{
+		var state = context.State<MxpState>();
+		switch (mode)
+		{
+			case 0: state.Line = MxpMode.Open; break;
+			case 1: state.Line = MxpMode.Secure; break;
+			case 2: state.Line = MxpMode.Locked; break;
+			case 3:
+				state.Line = state.Default = MxpMode.Open;
+				var first = state.Open.FirstOrDefault(element => element.First is not null)?.First;
+				if (first is not null) context.Close(first);
+				state.Open.Clear();
+				break;
+			case 4: state.TemporarySecure = true; break;
+			case 5: state.Line = state.Default = MxpMode.Open; break;
+			case 6: state.Line = state.Default = MxpMode.Secure; break;
+			case 7: state.Line = state.Default = MxpMode.Locked; break;
+			case >= 10 and <= 99:
+				state.Line = MxpMode.Secure;
+				if (state.LineTags.TryGetValue(mode, out var element) && state.Elements.TryGetValue(element, out var definition))
+				{
+					// The line is the element; the reader opens it and the line's end closes it.
+					var reader = new MxpReader { _context = context };
+					reader.OpenCustom(definition, new ParsedTag(definition.Name, false, []), lineTag: true);
+				}
+				else if (mode switch { 10 => MxpFlagMarkup.RoomName, 11 => MxpFlagMarkup.RoomDescription, 12 => MxpFlagMarkup.RoomExits, 19 => MxpFlagMarkup.Welcome, _ => null } is { } flag)
+				{
+					var markup = new MxpFlagMarkup(flag);
+					if (context.Open(markup)) state.Open.Add(new MxpOpenElement(flag, markup, openMode: false, lineTag: true));
+				}
+
+				break;
+		}
+	}
+
+	// ── ITagSink ────────────────────────────────────────────────────────────────
+
+	public void Text(ReadOnlySpan<char> text)
+	{
+		var state = State;
+		if (state.Capture is not null)
+		{
+			Captured(text, text);
+			return;
+		}
+
+		Context.Print(text);
+	}
+
+	public void Entity(ReadOnlySpan<char> name)
+	{
+		var decoded = TagSyntax.Entity(name, LookupEntity);
+		var state = State;
+		if (state.Capture is not null)
+		{
+			Captured($"&{name};", decoded ?? $"&{name};");
+			return;
+		}
+
+		Context.Print(decoded ?? $"&{name};");
+	}
+
+	public void Tag(ReadOnlySpan<char> body)
+	{
+		var state = State;
+		var secure = Secure;
+		state.TemporarySecure = false;
+
+		if (state.Capture is { } capture)
+		{
+			var inner = TagSyntax.Parse(body);
+			if (inner is not null && inner.Name.Equals(capture.Name, StringComparison.OrdinalIgnoreCase))
+			{
+				if (inner.Closing && state.CaptureDepth == 0)
+				{
+					FinishCapture();
+					return;
+				}
+
+				state.CaptureDepth += inner.Closing ? -1 : 1;
+			}
+
+			Captured($"<{body}>", []);
+			return;
+		}
+
+		if (!body.IsEmpty && body[0] == '!')
+		{
+			if (secure) Definition(body[1..]);
+			else Context.Diagnostics.UnhandledSequences++;
+			return;
+		}
+
+		var tag = TagSyntax.Parse(body, LookupEntity);
+		if (tag is null) return;
+
+		if (tag.Closing)
+		{
+			Close(tag.Name);
+			return;
+		}
+
+		var custom = state.Elements.TryGetValue(tag.Name, out var definition) ? definition : null;
+		var open = custom?.Open ?? OpenTags.Contains(tag.Name);
+		if (!secure && !open)
+		{
+			Context.Diagnostics.UnhandledSequences++;
+			return;
+		}
+
+		if (custom is not null)
+		{
+			OpenCustom(custom, tag, lineTag: false);
+			return;
+		}
+
+		if (!Element(tag, openMode: !secure)) Context.Diagnostics.UnhandledSequences++;
+	}
+
+	// ── Elements ────────────────────────────────────────────────────────────────
+
+	private bool Element(ParsedTag tag, bool openMode)
+	{
+		var context = Context;
+		switch (tag.Name.ToUpperInvariant())
+		{
+			case "B" or "BOLD" or "STRONG" or "H" or "HIGH":
+				OpenStyle(tag.Name, new AnsiStyle { Bold = true }, openMode);
+				return true;
+			case "I" or "ITALIC" or "EM":
+				OpenStyle(tag.Name, new AnsiStyle { Italic = true }, openMode);
+				return true;
+			case "U" or "UNDERLINE":
+				OpenStyle(tag.Name, new AnsiStyle { Underlined = true }, openMode);
+				return true;
+			case "S" or "STRIKEOUT" or "STRIKE":
+				OpenStyle(tag.Name, new AnsiStyle { StrikeThrough = true }, openMode);
+				return true;
+			case "C" or "COLOR":
+				OpenStyle(tag.Name, new AnsiStyle { Foreground = Color(tag.Get("FORE", 0)), Background = Color(tag.Get("BACK", 1)) }, openMode);
+				return true;
+			case "FONT":
+				OpenStyle(tag.Name, new AnsiStyle { Foreground = Color(tag.Get("COLOR")), Background = Color(tag.Get("BACK")) }, openMode);
+				return true;
+			case "SMALL" or "TT" or "P" or "NOBR":
+				return true;
+			case "BR":
+				State.InBreak = true;
+				context.EndLine();
+				State.InBreak = false;
+				return true;
+			case "SBR":
+				context.Print(" ");
+				return true;
+			case "A":
+				{
+					var href = tag.Get("HREF", 0);
+					IMarkup? link = href is not null && UrlSafety.IsSafeNavigableUrl(href)
+						? new AnsiMarkup(new AnsiStyle { LinkUrl = href, LinkKind = LinkKind.Url, LinkText = tag.Get("HINT", 1) })
+						: null;
+					OpenElement(tag.Name, link is null ? [] : [link], openMode);
+					return true;
+				}
+			case "SEND":
+				{
+					var href = tag.Get("HREF", 0);
+					if (href is null || href.Contains("&text;", StringComparison.OrdinalIgnoreCase))
+					{
+						StartCapture(tag);
+						return true;
+					}
+
+					OpenSend(tag, href, openMode);
+					return true;
+				}
+			case "VAR" or "V":
+				StartCapture(tag);
+				return true;
+			case "EXPIRE":
+				context.Point(new ExpireLinksMarkup(tag.Get("NAME", 0)));
+				return true;
+			case "VERSION":
+				if ((context.Identity.Answers & ClientAnswers.Mxp) != 0)
+				{
+					context.Reply(string.Create(CultureInfo.InvariantCulture,
+						$"\e[1z<VERSION MXP=1.0 CLIENT={Quote(context.Identity.Name)} VERSION={Quote(context.Identity.Version)}>\n"));
+				}
+
+				return true;
+			case "SUPPORT":
+				if ((context.Identity.Answers & ClientAnswers.Mxp) != 0) context.Reply(Supports(tag));
+				return true;
+			case "IMAGE":
+				Image(tag);
+				return true;
+			case "SOUND" or "MUSIC":
+				Sound(tag);
+				return true;
+			case "FRAME":
+				{
+					var name = tag.Get("NAME", 0);
+					if (name is not null) State.FrameTitles[name] = tag.Get("TITLE");
+					return true;
+				}
+			case "DEST":
+				{
+					var name = tag.Get("NAME", 0);
+					if (string.IsNullOrEmpty(name)) return false;
+					State.FrameTitles.TryGetValue(name, out var title);
+					OpenElement(tag.Name, [new PaneMarkup(name, title)], openMode);
+					return true;
+				}
+			case "RELOCATE":
+				{
+					var host = tag.Get("HOST", 0);
+					if (host is null || !int.TryParse(tag.Get("PORT", 1), NumberStyles.None, CultureInfo.InvariantCulture, out var port)) return false;
+					context.Point(new RelocateMarkup(host, port, tag.Has("QUIET")));
+					return true;
+				}
+			case "USER":
+				context.Point(new LoginPromptMarkup(LoginField.User));
+				return true;
+			case "PASSWORD":
+				context.Point(new LoginPromptMarkup(LoginField.Password));
+				return true;
+			case "GAUGE" or "STAT":
+				// A gauge stands for a variable the host already has from VAR and ENTITY; there is no text to show.
+				return true;
+			default:
+				return false;
+		}
+	}
+
+	private void OpenStyle(string name, AnsiStyle style, bool openMode) =>
+		OpenElement(name, style.IsNone ? [] : [new AnsiMarkup(style)], openMode);
+
+	private void OpenElement(string name, IMarkup[] markups, bool openMode, bool lineTag = false)
+	{
+		IMarkup? first = null;
+		foreach (var markup in markups)
+		{
+			if (!Context.Open(markup)) break;
+			first ??= markup;
+		}
+
+		State.Open.Add(new MxpOpenElement(name, first, openMode, lineTag));
+	}
+
+	private void Close(string name)
+	{
+		var state = State;
+		var index = state.Open.FindLastIndex(element => element.Name.Equals(name, StringComparison.OrdinalIgnoreCase));
+		if (index >= 0) CloseFrom(index);
+	}
+
+	private void CloseFrom(int index)
+	{
+		var state = State;
+		for (var i = index; i < state.Open.Count; i++)
+		{
+			if (state.Open[i].First is { } first)
+			{
+				Context.Close(first);
+				break;
+			}
+		}
+
+		state.Open.RemoveRange(index, state.Open.Count - index);
+	}
+
+	private void OpenSend(ParsedTag tag, string href, bool openMode)
+	{
+		var commands = href.Split('|');
+		var hints = tag.Get("HINT", 1)?.Split('|') ?? [];
+		var prompt = tag.Has("PROMPT");
+
+		// With one hint more than commands, the first is the link's own and the rest label the menu.
+		string? hint;
+		string[] labels;
+		if (hints.Length == commands.Length + 1)
+		{
+			hint = hints[0];
+			labels = hints[1..];
+		}
+		else
+		{
+			hint = hints.Length > 0 ? hints[0] : null;
+			labels = hints.Length == commands.Length ? hints : commands;
+		}
+
+		var link = new AnsiMarkup(new AnsiStyle { LinkUrl = commands[0], LinkKind = LinkKind.Command, LinkText = hint });
+		if (commands.Length == 1 && !prompt)
+		{
+			OpenElement(tag.Name, [link], openMode);
+			return;
+		}
+
+		var choices = new CommandChoice[commands.Length];
+		for (var i = 0; i < commands.Length; i++) choices[i] = new CommandChoice(labels[i], commands[i]);
+		OpenElement(tag.Name, [new CommandMenuMarkup(choices, hint, prompt), link], openMode);
+	}
+
+	private void OpenCustom(MxpElementDefinition definition, ParsedTag tag, bool lineTag)
+	{
+		var state = State;
+		var before = Context.Elements.Count;
+		var opened = state.Open.Count;
+
+		if (definition.Flag is { } flag) Context.Open(new MxpFlagMarkup(flag));
+
+		// The definition's tags, with the element's attributes put in for &name;, run as secure tags.
+		var expanded = Expand(definition, tag);
+		var replay = new TagScanner();
+		state.TemporarySecure = false;
+		var saved = state.Line;
+		state.Line = MxpMode.Secure;
+		replay.Feed(expanded, this);
+		state.Line = saved;
+
+		// What the definition opened is one element now, closed together.
+		if (state.Open.Count > opened) state.Open.RemoveRange(opened, state.Open.Count - opened);
+		var first = Context.Elements.Count > before ? Context.Elements[before] : null;
+		if (definition.Empty)
+		{
+			if (first is not null) Context.Close(first);
+			return;
+		}
+
+		state.Open.Add(new MxpOpenElement(definition.Name, first, openMode: !Secure && !lineTag && definition.Open, lineTag));
+	}
+
+	private static string Expand(MxpElementDefinition definition, ParsedTag tag)
+	{
+		var text = definition.Definition;
+		var position = 0;
+		foreach (var attribute in definition.Attributes)
+		{
+			var name = attribute.Name ?? attribute.Value;
+			var value = tag.Get(name, position++) ?? (attribute.Name is null ? string.Empty : attribute.Value);
+			text = text.Replace($"&{name};", value, StringComparison.OrdinalIgnoreCase);
+		}
+
+		return text;
+	}
+
+	private void Definition(ReadOnlySpan<char> body)
+	{
+		var tag = TagSyntax.Parse(body);
+		if (tag is null) return;
+		var state = State;
+		var name = tag.Get("NAME", 0);
+		if (name is null) return;
+
+		switch (tag.Name.ToUpperInvariant())
+		{
+			case "ELEMENT" or "EL":
+				{
+					if (tag.Has("DELETE"))
+					{
+						state.Elements.Remove(name);
+						return;
+					}
+
+					var attributes = TagSyntax.Parse("x " + (tag.Get("ATT") ?? string.Empty))?.Arguments ?? [];
+					var definition = new MxpElementDefinition(name, tag.Get("DEFINITION", 1) ?? string.Empty, attributes, tag.Get("FLAG"), tag.Has("OPEN"), tag.Has("EMPTY"));
+					state.Elements[name] = definition;
+					if (int.TryParse(tag.Get("TAG"), NumberStyles.None, CultureInfo.InvariantCulture, out var number) && number is >= 20 and <= 99)
+					{
+						state.LineTags[number] = name;
+					}
+
+					return;
+				}
+			case "ATTLIST" or "AT":
+				{
+					if (!state.Elements.TryGetValue(name, out var definition)) return;
+					var attributes = TagSyntax.Parse("x " + (tag.Get("ATT", 1) ?? string.Empty))?.Arguments ?? [];
+					state.Elements[name] = definition with { Attributes = attributes };
+					return;
+				}
+			case "TAG":
+				{
+					var number = tag.Get("INDEX", 0);
+					var element = tag.Get("ELEMENT", 1) ?? tag.Get("NAME");
+					if (int.TryParse(number, NumberStyles.None, CultureInfo.InvariantCulture, out var index) && element is not null) state.LineTags[index] = element;
+					return;
+				}
+			case "ENTITY" or "EN":
+				{
+					if (tag.Has("DELETE") || tag.Has("REMOVE"))
+					{
+						state.Entities.Remove(name);
+						Context.Raise(new VariableEvent(name, null));
+						return;
+					}
+
+					var value = tag.Get("VALUE", 1) ?? string.Empty;
+					if (tag.Has("ADD") && state.Entities.TryGetValue(name, out var existing)) value = existing + "|" + value;
+					state.Entities[name] = value;
+					if (!tag.Has("PRIVATE")) Context.Raise(new VariableEvent(name, value));
+					return;
+				}
+		}
+	}
+
+	// ── Capturing the text of SEND and VAR ──────────────────────────────────────
+
+	private void StartCapture(ParsedTag tag)
+	{
+		var state = State;
+		state.Capture = tag;
+		state.CaptureDepth = 0;
+		state.CaptureRaw.Clear();
+		state.CaptureText.Clear();
+	}
+
+	private void Captured(ReadOnlySpan<char> raw, ReadOnlySpan<char> text)
+	{
+		var state = State;
+		state.CaptureRaw.Append(raw);
+		state.CaptureText.Append(text);
+		if (state.CaptureRaw.Length > MaxCapture) FinishCapture();
+	}
+
+	private void FinishCapture()
+	{
+		var state = State;
+		var tag = state.Capture!;
+		var raw = state.CaptureRaw.ToString();
+		var text = state.CaptureText.ToString();
+		state.Capture = null;
+
+		var name = tag.Name.ToUpperInvariant();
+		if (name == "SEND")
+		{
+			var href = tag.Get("HREF", 0)?.Replace("&text;", text, StringComparison.OrdinalIgnoreCase) ?? text;
+			var hint = tag.Get("HINT", 1)?.Replace("&text;", text, StringComparison.OrdinalIgnoreCase);
+			var arguments = tag.Arguments.Where(argument => argument.Name is not null && !argument.Name.Equals("HREF", StringComparison.OrdinalIgnoreCase)
+				&& !argument.Name.Equals("HINT", StringComparison.OrdinalIgnoreCase)).ToList();
+			if (hint is not null) arguments.Add(new TagArgument("HINT", hint));
+			if (tag.Has("PROMPT")) arguments.Add(new TagArgument(null, "PROMPT"));
+			if (href.Length > 0) OpenSend(tag with { Arguments = arguments }, href, openMode: false);
+			else OpenElement(tag.Name, [], openMode: false);
+		}
+		else
+		{
+			var variable = tag.Get("NAME", 0);
+			if (!string.IsNullOrEmpty(variable))
+			{
+				state.Entities[variable] = text;
+				if (!tag.Has("PRIVATE")) Context.Raise(new VariableEvent(variable, text));
+				OpenElement(tag.Name, [new VariableMarkup(variable)], openMode: false);
+			}
+			else
+			{
+				OpenElement(tag.Name, [], openMode: false);
+			}
+		}
+
+		var saved = state.Line;
+		state.Line = MxpMode.Secure;
+		new TagScanner().Feed(raw, this);
+		state.Line = saved;
+		Close(tag.Name);
+	}
+
+	// ── Pictures and sounds ─────────────────────────────────────────────────────
+
+	private void Image(ParsedTag tag)
+	{
+		var file = tag.Get("FNAME", 0);
+		if (string.IsNullOrEmpty(file)) return;
+		var source = Address(tag.Get("URL"), file);
+		var (width, widthCells) = Size(tag.Get("W"));
+		var (height, heightCells) = Size(tag.Get("H"));
+		var align = Enum.TryParse<ImageAlign>(tag.Get("ALIGN"), ignoreCase: true, out var parsed) ? parsed : (ImageAlign?)null;
+		var image = new ImageMarkup(source, null, width, height, align);
+
+		if (widthCells > 0 && heightCells > 0)
+		{
+			// Sized in cells: drawn over the cells the server leaves for it on this line and the ones after.
+			State.Overlays.Add((image, heightCells, widthCells, Context.Column, 0));
+			return;
+		}
+
+		Context.Write(file, image);
+	}
+
+	private static (int? Pixels, int Cells) Size(string? value)
+	{
+		if (string.IsNullOrEmpty(value)) return (null, 0);
+		if (value.EndsWith('c') && int.TryParse(value.AsSpan(0, value.Length - 1), NumberStyles.None, CultureInfo.InvariantCulture, out var cells)) return (null, cells);
+		var digits = value.EndsWith("px", StringComparison.OrdinalIgnoreCase) ? value[..^2] : value;
+		return int.TryParse(digits, NumberStyles.None, CultureInfo.InvariantCulture, out var pixels) && pixels > 0 ? (pixels, 0) : (null, 0);
+	}
+
+	private void DrawOverlays()
+	{
+		var overlays = State.Overlays;
+		if (overlays.Count == 0) return;
+		var context = Context;
+		var cursor = context.Column;
+		for (var i = 0; i < overlays.Count; i++)
+		{
+			var (image, rows, columns, column, next) = overlays[i];
+			context.MoveToColumn(column);
+			context.Write(new string(' ', columns), image with { Row = new PictureRow(next, rows, columns) });
+			overlays[i] = (image, rows, columns, column, next + 1);
+		}
+
+		overlays.RemoveAll(overlay => overlay.Next >= overlay.Rows);
+		context.MoveToColumn(cursor);
+	}
+
+	private void Sound(ParsedTag tag)
+	{
+		var music = tag.Name.Equals("MUSIC", StringComparison.OrdinalIgnoreCase);
+		var channel = music ? SoundChannel.Music : SoundChannel.Effects;
+		var file = tag.Get("FNAME", 0);
+		if (string.IsNullOrEmpty(file)) return;
+		if (file.Equals("Off", StringComparison.OrdinalIgnoreCase))
+		{
+			Context.Point(new SoundStopMarkup(channel));
+			return;
+		}
+
+		int? volume = int.TryParse(tag.Get("V"), NumberStyles.None, CultureInfo.InvariantCulture, out var v) ? Math.Clamp(v, 0, 100) : null;
+		int? repeats = int.TryParse(tag.Get("L"), NumberStyles.AllowLeadingSign, CultureInfo.InvariantCulture, out var l)
+			? l < 0 ? SoundMarkup.Forever : l
+			: null;
+		var continues = music && tag.Get("C") == "1";
+		Context.Point(new SoundMarkup(Address(tag.Get("U"), file), channel, volume, repeats, continues));
+	}
+
+	private static string Address(string? directory, string file)
+	{
+		if (string.IsNullOrEmpty(directory) || Uri.TryCreate(file, UriKind.Absolute, out _)) return file;
+		return directory.EndsWith('/') ? directory + file : directory + "/" + file;
+	}
+
+	// ── Helpers ─────────────────────────────────────────────────────────────────
+
+	private string? LookupEntity(string name) => State.Entities.TryGetValue(name, out var value) ? value : null;
+
+	private static AnsiColor? Color(string? name)
+	{
+		if (string.IsNullOrWhiteSpace(name)) return null;
+		name = name.Trim();
+		if (name[0] == '#' && name.Length == 7
+			&& int.TryParse(name.AsSpan(1), NumberStyles.AllowHexSpecifier, CultureInfo.InvariantCulture, out var value))
+		{
+			return new AnsiColor.Rgb((byte)(value >> 16), (byte)(value >> 8), (byte)value);
+		}
+
+		var known = System.Drawing.Color.FromName(name);
+		return known.IsKnownColor && !known.IsSystemColor ? new AnsiColor.Rgb(known.R, known.G, known.B) : null;
+	}
+
+	private static string Quote(string value) => "\"" + value.Replace("\"", "'", StringComparison.Ordinal) + "\"";
+
+	private static string Supports(ParsedTag tag)
+	{
+		var supported = new HashSet<string>(MxpPlugin.Supported, StringComparer.OrdinalIgnoreCase);
+		var answer = new StringBuilder("\e[1z<SUPPORTS");
+		var asked = tag.Arguments.Where(argument => argument.Name is null).Select(argument => argument.Value).ToList();
+		if (asked.Count == 0)
+		{
+			foreach (var name in MxpPlugin.Supported) answer.Append(" +").Append(name.ToLowerInvariant());
+		}
+		else
+		{
+			foreach (var item in asked)
+			{
+				// "send.prompt" asks about an attribute; the element's answer stands for it.
+				var element = item.Split('.')[0];
+				answer.Append(supported.Contains(element) ? " +" : " -").Append(item.ToLowerInvariant());
+			}
+		}
+
+		return answer.Append(">\n").ToString();
+	}
+}
diff --git a/MarkupString.Mxp/MarkupString.Mxp.csproj b/MarkupString.Mxp/MarkupString.Mxp.csproj
index 079ec3e..92349ca 100644
--- a/MarkupString.Mxp/MarkupString.Mxp.csproj
+++ b/MarkupString.Mxp/MarkupString.Mxp.csproj
@@ -27,5 +27,6 @@
 
   <ItemGroup>
     <ProjectReference Include="..\MarkupString\MarkupString.csproj" />
+    <ProjectReference Include="..\MarkupString.Ansi\MarkupString.Ansi.csproj" />
   </ItemGroup>
 </Project>
diff --git a/MarkupString.Mxp/PublicAPI.Unshipped.txt b/MarkupString.Mxp/PublicAPI.Unshipped.txt
index 7dc5c58..ea461a6 100644
--- a/MarkupString.Mxp/PublicAPI.Unshipped.txt
+++ b/MarkupString.Mxp/PublicAPI.Unshipped.txt
@@ -1 +1,26 @@
 #nullable enable
+MarkupString.Mxp.Decoding.MxpDecoding
+MarkupString.Mxp.Decoding.MxpFlagMarkup
+MarkupString.Mxp.Decoding.MxpFlagMarkup.<Clone>$() -> MarkupString.Mxp.Decoding.MxpFlagMarkup!
+MarkupString.Mxp.Decoding.MxpFlagMarkup.Deconstruct(out string! Flag) -> void
+MarkupString.Mxp.Decoding.MxpFlagMarkup.Equals(MarkupString.Mxp.Decoding.MxpFlagMarkup? other) -> bool
+MarkupString.Mxp.Decoding.MxpFlagMarkup.Flag.get -> string!
+MarkupString.Mxp.Decoding.MxpFlagMarkup.Flag.init -> void
+MarkupString.Mxp.Decoding.MxpFlagMarkup.MxpFlagMarkup(string! Flag) -> void
+MarkupString.Mxp.Decoding.MxpPlugin
+MarkupString.Mxp.Decoding.MxpPlugin.Name.get -> string!
+MarkupString.Mxp.Decoding.MxpPlugin.Register(MarkupString.Decoding.DecoderBuilder! builder) -> void
+const MarkupString.Mxp.Decoding.MxpDecoding.Protocol = "mxp" -> string!
+const MarkupString.Mxp.Decoding.MxpFlagMarkup.RoomDescription = "RoomDesc" -> string!
+const MarkupString.Mxp.Decoding.MxpFlagMarkup.RoomExits = "RoomExit" -> string!
+const MarkupString.Mxp.Decoding.MxpFlagMarkup.RoomName = "RoomName" -> string!
+const MarkupString.Mxp.Decoding.MxpFlagMarkup.Welcome = "Welcome" -> string!
+override MarkupString.Mxp.Decoding.MxpFlagMarkup.Equals(object? obj) -> bool
+override MarkupString.Mxp.Decoding.MxpFlagMarkup.GetHashCode() -> int
+override MarkupString.Mxp.Decoding.MxpFlagMarkup.ToString() -> string!
+static MarkupString.Mxp.Decoding.MxpDecoding.FlagCodec.get -> MarkupString.IMarkupCodec!
+static MarkupString.Mxp.Decoding.MxpDecoding.WithMxp(this MarkupString.Decoding.DecoderRegistry! registry) -> MarkupString.Decoding.DecoderRegistry!
+static MarkupString.Mxp.Decoding.MxpFlagMarkup.operator !=(MarkupString.Mxp.Decoding.MxpFlagMarkup? left, MarkupString.Mxp.Decoding.MxpFlagMarkup? right) -> bool
+static MarkupString.Mxp.Decoding.MxpFlagMarkup.operator ==(MarkupString.Mxp.Decoding.MxpFlagMarkup? left, MarkupString.Mxp.Decoding.MxpFlagMarkup? right) -> bool
+static MarkupString.Mxp.Decoding.MxpPlugin.Instance.get -> MarkupString.Mxp.Decoding.MxpPlugin!
+static MarkupString.Mxp.Decoding.MxpPlugin.Supported.get -> System.Collections.Generic.IReadOnlyList<string!>!
diff --git a/MarkupString.Tests/Decoding/MxpDecodingTests.cs b/MarkupString.Tests/Decoding/MxpDecodingTests.cs
new file mode 100644
index 0000000..734a819
--- /dev/null
+++ b/MarkupString.Tests/Decoding/MxpDecodingTests.cs
@@ -0,0 +1,237 @@
+using MarkupString.Ansi;
+using MarkupString.Ansi.Decoding;
+using MarkupString.Decoding;
+using MarkupString.Display;
+using MarkupString.Mxp;
+using MarkupString.Mxp.Decoding;
+
+public class MxpDecodingTests
+{
+	private static readonly DecoderRegistry Registry = VtDecoding.Terminal.WithMxp();
+
+	private static (List<DisplayLine> Lines, List<DecodeEvent> Events, Decoder Decoder) Decode(string text, DecoderOptions? options = null)
+	{
+		var decoder = Registry.CreateDecoder(options);
+		var events = new List<DecodeEvent>();
+		decoder.EventRaised += events.Add;
+		decoder.EnableProtocol(MxpDecoding.Protocol);
+		var lines = new List<DisplayLine>(decoder.Feed(text));
+		if (decoder.HasPendingLine) lines.Add(decoder.EndLine());
+		return (lines, events, decoder);
+	}
+
+	private static IReadOnlyList<DisplaySpan> Spans(DisplayLine line) => SpanRenderer.Render(line.Content, AnsiDisplay.Default, new DisplayOptions());
+
+	private static IEnumerable<IMarkup> Markups(DisplayLine line) => line.Content.Runs.SelectMany(run => run.Markups);
+
+	[Test]
+	public async Task OpenTags_WorkOnAnOpenLine()
+	{
+		var (lines, _, _) = Decode("<B>bold</B> <COLOR red>red</COLOR>\n");
+		var spans = Spans(lines[0]);
+		await Assert.That(spans.Select(span => span.Text)).IsEquivalentTo(["bold", " ", "red"]);
+		await Assert.That(spans[0].Style.Has(TextAttributes.Bold)).IsTrue();
+		await Assert.That(spans[2].Style.Foreground).IsEqualTo(new RgbColor(255, 0, 0));
+	}
+
+	[Test]
+	public async Task SecureTags_AreDroppedOnAnOpenLine()
+	{
+		var (lines, _, decoder) = Decode("<SEND look>look</SEND>\n");
+		await Assert.That(lines[0].Content.ToPlainText()).IsEqualTo("look");
+		await Assert.That(Spans(lines[0]).Single().Style.Interaction).IsNull();
+		await Assert.That(decoder.Diagnostics.UnhandledSequences).IsEqualTo(1);
+	}
+
+	[Test]
+	public async Task Send_OnASecureLine_IsACommand()
+	{
+		var (lines, _, _) = Decode("\e[1z<SEND href=\"look sword\" hint=\"Look at it\">sword</SEND> here\n");
+		var spans = Spans(lines[0]);
+		await Assert.That(spans[0].Text).IsEqualTo("sword");
+		await Assert.That(spans[0].Style.Interaction).IsEqualTo(new Interaction(InteractionKind.Command, "look sword") { Hint = "Look at it" });
+		await Assert.That(spans[1].Style.Interaction).IsNull();
+	}
+
+	[Test]
+	public async Task Send_WithoutHref_SendsItsText()
+	{
+		var (lines, _, _) = Decode("\e[1z<SEND>north</SEND>\n");
+		await Assert.That(Spans(lines[0]).Single().Style.Interaction!.Target).IsEqualTo("north");
+	}
+
+	[Test]
+	public async Task Send_TextSubstitution()
+	{
+		var (lines, _, _) = Decode("\e[1z<SEND \"get &text;\">sword</SEND>\n");
+		await Assert.That(Spans(lines[0]).Single().Style.Interaction!.Target).IsEqualTo("get sword");
+	}
+
+	[Test]
+	public async Task Send_Menu()
+	{
+		var (lines, _, _) = Decode("\e[1z<SEND \"buy sword|look sword\" hint=\"Sword|Buy|Look\">sword</SEND>\n");
+		var interaction = Spans(lines[0]).Single().Style.Interaction!;
+		await Assert.That(interaction.Target).IsEqualTo("buy sword");
+		await Assert.That(interaction.Hint).IsEqualTo("Sword");
+		await Assert.That(interaction.Choices!).IsEquivalentTo([new CommandChoice("Buy", "buy sword"), new CommandChoice("Look", "look sword")]);
+	}
+
+	[Test]
+	public async Task Send_Prompt()
+	{
+		var (lines, _, _) = Decode("\e[1z<SEND \"say \" PROMPT>talk</SEND>\n");
+		await Assert.That(Spans(lines[0]).Single().Style.Interaction!.Kind).IsEqualTo(InteractionKind.Prompt);
+	}
+
+	[Test]
+	public async Task OpenElements_CloseAtTheEndOfTheLine()
+	{
+		var (lines, _, _) = Decode("<B>one\ntwo\n");
+		await Assert.That(Spans(lines[1]).Single().Style.Has(TextAttributes.Bold)).IsFalse();
+	}
+
+	[Test]
+	public async Task LockedLine_IsText()
+	{
+		var (lines, _, _) = Decode("\e[2z<B>&lt;\n<B>x</B>\n");
+		await Assert.That(lines[0].Content.ToPlainText()).IsEqualTo("<B>&lt;");
+		await Assert.That(lines[1].Content.ToPlainText()).IsEqualTo("x");
+	}
+
+	[Test]
+	public async Task Entities()
+	{
+		var (lines, _, _) = Decode("a &lt;b&gt; &amp; &#65;&#x42; &nope; & c\n");
+		await Assert.That(lines[0].Content.ToPlainText()).IsEqualTo("a <b> & AB &nope; & c");
+	}
+
+	[Test]
+	public async Task TagsSplitAcrossFeeds()
+	{
+		var decoder = Registry.CreateDecoder();
+		decoder.EnableProtocol(MxpDecoding.Protocol);
+		decoder.Feed("<CO");
+		decoder.Feed("LOR re");
+		var lines = decoder.Feed("d>x</COLOR>\n");
+		await Assert.That(SpanRenderer.Render(lines[0].Content, AnsiDisplay.Default, new DisplayOptions()).Single().Style.Foreground).IsEqualTo(new RgbColor(255, 0, 0));
+	}
+
+	[Test]
+	public async Task Comments_AreDropped()
+	{
+		var (lines, _, _) = Decode("a<!-- not <B> shown -->b\n");
+		await Assert.That(lines[0].Content.ToPlainText()).IsEqualTo("ab");
+	}
+
+	[Test]
+	public async Task SgrInsideMxp_Wins()
+	{
+		var (lines, _, _) = Decode("<COLOR red>\e[32mgreen\e[0m</COLOR>\n");
+		await Assert.That(Spans(lines[0]).Single().Style.Foreground).IsEqualTo(new RgbColor(0, 170, 0));
+	}
+
+	[Test]
+	public async Task CustomElements()
+	{
+		var (lines, _, _) = Decode("\e[1z<!ELEMENT Exit '<SEND href=\"&dir;\"><COLOR cyan>' ATT='dir' FLAG=RoomExit>\n\e[1z<Exit north>N</Exit> S\n");
+		var spans = Spans(lines[1]);
+		await Assert.That(spans[0].Text).IsEqualTo("N");
+		await Assert.That(spans[0].Style.Interaction!.Target).IsEqualTo("north");
+		await Assert.That(spans[0].Style.Foreground).IsEqualTo(new RgbColor(0, 255, 255));
+		await Assert.That(Markups(lines[1]).OfType<MxpFlagMarkup>().First().Flag).IsEqualTo("RoomExit");
+		await Assert.That(spans[1].Style).IsEqualTo(DisplayStyle.Plain);
+	}
+
+	[Test]
+	public async Task LineTags_MarkTheLine()
+	{
+		var (lines, _, _) = Decode("\e[10zThe Square\nnext\n");
+		await Assert.That(Markups(lines[0]).OfType<MxpFlagMarkup>().Single().Flag).IsEqualTo(MxpFlagMarkup.RoomName);
+		await Assert.That(Markups(lines[1]).Any()).IsFalse();
+	}
+
+	[Test]
+	public async Task Version_And_Support_AreAnswered()
+	{
+		var options = new DecoderOptions { Identity = new ClientIdentity { Name = "Test", Version = "3" } };
+		var (_, events, _) = Decode("\e[1z<VERSION>\e[1z<SUPPORT send image.url frob>", options);
+		await Assert.That(events.OfType<ReplyEvent>().Select(reply => reply.Text)).IsEquivalentTo([
+			"\e[1z<VERSION MXP=1.0 CLIENT=\"Test\" VERSION=\"3\">\n",
+			"\e[1z<SUPPORTS +send +image.url -frob>\n",
+		]);
+	}
+
+	[Test]
+	public async Task Var_SetsAVariable_AndShowsItsText()
+	{
+		var (lines, events, _) = Decode("\e[1zHP: <VAR hp>42</VAR>\n");
+		await Assert.That(events.OfType<VariableEvent>().Single()).IsEqualTo(new VariableEvent("hp", "42"));
+		await Assert.That(lines[0].Content.ToPlainText()).IsEqualTo("HP: 42");
+		await Assert.That(Markups(lines[0]).OfType<VariableMarkup>().Single().Name).IsEqualTo("hp");
+	}
+
+	[Test]
+	public async Task Entity_Definition_IsUsedAndPublished()
+	{
+		var (lines, events, _) = Decode("\e[1z<!ENTITY hero \"Ada\">\nHello &hero;\n");
+		await Assert.That(lines[^1].Content.ToPlainText()).IsEqualTo("Hello Ada");
+		await Assert.That(events.OfType<VariableEvent>().Single()).IsEqualTo(new VariableEvent("hero", "Ada"));
+	}
+
+	[Test]
+	public async Task Br_BreaksWithoutEndingTheSecureLine()
+	{
+		var (lines, _, _) = Decode("\e[1zone<BR><SEND x>two</SEND>\n");
+		await Assert.That(lines.Select(line => line.Content.ToPlainText())).IsEquivalentTo(["one", "two"]);
+		await Assert.That(Spans(lines[1]).Single().Style.Interaction).IsNotNull();
+	}
+
+	[Test]
+	public async Task Reset_ClosesEverything()
+	{
+		var (lines, _, _) = Decode("\e[6z<B>bold\e[3zplain\n");
+		var spans = Spans(lines[0]);
+		await Assert.That(spans[^1].Text).IsEqualTo("plain");
+		await Assert.That(spans[^1].Style.Has(TextAttributes.Bold)).IsFalse();
+	}
+
+	[Test]
+	public async Task LineModes_AreIgnoredUntilMxpIsOn()
+	{
+		var decoder = Registry.CreateDecoder();
+		var lines = decoder.Feed("\e[1z<B>x</B>\n");
+		await Assert.That(lines[0].Content.ToPlainText()).IsEqualTo("<B>x</B>");
+		await Assert.That(decoder.Diagnostics.UnhandledSequences).IsEqualTo(0);
+	}
+
+	[Test]
+	public async Task WhatThisPackageWrites_ReadsBack()
+	{
+		var registry = MarkupRegistry.Empty.WithAnsi().WithMxp().WithMxpSecureLines();
+		var link = MarkupText.Wrap(new AnsiMarkup(new AnsiStyle { LinkUrl = "look", LinkKind = LinkKind.Command, LinkText = "Look" }), "look");
+		var text = MarkupText.Concat([
+			MarkupText.Sound("https://example.test/sounds/door.wav", volume: 80),
+			MarkupText.Pane(MarkupText.Concat([MarkupText.Plain("North: "), link]), "map", "The Map")]);
+		var wire = text.Render(MarkupFormat.Mxp, registry);
+
+		var (lines, _, _) = Decode(wire + "\n");
+		var line = lines.Single();
+		await Assert.That(line.Content.ToPlainText()).IsEqualTo("North: look");
+		await Assert.That(Markups(line).OfType<SoundMarkup>().Single()).IsEqualTo(new SoundMarkup("https://example.test/sounds/door.wav", Volume: 80));
+		await Assert.That(Markups(line).OfType<PaneMarkup>().First()).IsEqualTo(new PaneMarkup("map", "The Map"));
+		var spans = Spans(line);
+		await Assert.That(spans[^1].Style.Interaction).IsEqualTo(new Interaction(InteractionKind.Command, "look") { Hint = "Look" });
+	}
+
+	[Test]
+	public async Task Image_InCells_IsDrawnOverTheLines()
+	{
+		var (lines, _, _) = Decode("\e[1z<IMAGE cat.png URL=\"https://example.test/\" W=2c H=2c>  a\n  b\n");
+		var first = lines[0].Content.Runs.SelectMany(run => run.Markups).OfType<ImageMarkup>().Single();
+		await Assert.That(first.Source).IsEqualTo("https://example.test/cat.png");
+		await Assert.That(first.Row!.Value.Row).IsEqualTo(0);
+		await Assert.That(lines[1].Content.Runs.SelectMany(run => run.Markups).OfType<ImageMarkup>().Single().Row!.Value.Row).IsEqualTo(1);
+		await Assert.That(lines[1].Content.ToPlainText()).IsEqualTo("  b");
+	}
+}
diff --git a/MarkupString/Decoding/TagScanner.cs b/MarkupString/Decoding/TagScanner.cs
new file mode 100644
index 0000000..d9e9e19
--- /dev/null
+++ b/MarkupString/Decoding/TagScanner.cs
@@ -0,0 +1,187 @@
+using System.Text;
+namespace MarkupString.Decoding;
+
+/// <summary>What a <see cref="TagScanner"/> finds.</summary>
+public interface ITagSink
+{
+	/// <summary>Whether <c>&lt;</c> and <c>&amp;</c> start markup now; when false they are text.</summary>
+	bool ReadsMarkup { get; }
+
+	/// <summary>Text.</summary>
+	void Text(ReadOnlySpan<char> text);
+
+	/// <summary>A tag: what was between <c>&lt;</c> and <c>&gt;</c>.</summary>
+	void Tag(ReadOnlySpan<char> body);
+
+	/// <summary>An entity: what was between <c>&amp;</c> and <c>;</c>.</summary>
+	void Entity(ReadOnlySpan<char> name);
+}
+
+/// <summary>
+/// Splits a tag protocol's text (MXP, Pueblo's HTML) into text, tags and entities, across as many feeds as it
+/// arrives in. Comments (<c>&lt;!-- --&gt;</c>) are dropped. A tag or entity too long to be one is text.
+/// </summary>
+public sealed class TagScanner
+{
+	private enum State
+	{
+		Text,
+		Tag,
+		Quoted,
+		Comment,
+		Entity,
+	}
+
+	private readonly StringBuilder _pending = new();
+	private State _state;
+	private char _quote;
+
+	/// <summary>The longest tag read as one.</summary>
+	public int MaxTagLength { get; init; } = 8192;
+
+	/// <summary>The longest entity name read as one.</summary>
+	public int MaxEntityLength { get; init; } = 32;
+
+	/// <summary>Whether a tag or an entity is half read.</summary>
+	public bool InMarkup => _state != State.Text;
+
+	/// <summary>Reads <paramref name="text"/>.</summary>
+	public void Feed(ReadOnlySpan<char> text, ITagSink sink)
+	{
+		ArgumentNullException.ThrowIfNull(sink);
+		var start = 0;
+		for (var i = 0; i < text.Length; i++)
+		{
+			var c = text[i];
+			switch (_state)
+			{
+				case State.Text:
+					if (!sink.ReadsMarkup || (c != '<' && c != '&')) continue;
+					if (i > start) sink.Text(text[start..i]);
+					_pending.Clear();
+					_state = c == '<' ? State.Tag : State.Entity;
+					start = i + 1;
+					continue;
+
+				case State.Tag:
+					if (c is '"' or '\'')
+					{
+						_quote = c;
+						_state = State.Quoted;
+					}
+					else if (c == '>')
+					{
+						_state = State.Text;
+						start = i + 1;
+						sink.Tag(Take());
+						continue;
+					}
+
+					_pending.Append(c);
+					if (_pending.Length == 3 && _pending.Equals("!--"))
+					{
+						_pending.Clear();
+						_state = State.Comment;
+					}
+					else if (_pending.Length > MaxTagLength)
+					{
+						Abandon('<', sink);
+						start = i + 1;
+					}
+
+					continue;
+
+				case State.Quoted:
+					_pending.Append(c);
+					if (c == _quote) _state = State.Tag;
+					else if (_pending.Length > MaxTagLength)
+					{
+						Abandon('<', sink);
+						start = i + 1;
+					}
+
+					continue;
+
+				case State.Comment:
+					_pending.Append(c);
+					if (_pending.Length > 3) _pending.Remove(0, _pending.Length - 3);
+					if (_pending.Equals("-->"))
+					{
+						_pending.Clear();
+						_state = State.Text;
+						start = i + 1;
+					}
+
+					continue;
+
+				case State.Entity:
+					if (c == ';')
+					{
+						_state = State.Text;
+						start = i + 1;
+						sink.Entity(Take());
+						continue;
+					}
+
+					if (char.IsAsciiLetterOrDigit(c) || c is '#' or '_' or '-' or '.')
+					{
+						_pending.Append(c);
+						if (_pending.Length > MaxEntityLength)
+						{
+							Abandon('&', sink);
+							start = i + 1;
+						}
+
+						continue;
+					}
+
+					// Not an entity after all: the ampersand and what followed are text, this character included.
+					Abandon('&', sink);
+					start = i;
+					i--;
+					continue;
+			}
+		}
+
+		if (_state == State.Text && start < text.Length) sink.Text(text[start..]);
+	}
+
+	/// <summary>Ends what is half read, as text: a line ended inside a tag.</summary>
+	public void Flush(ITagSink sink)
+	{
+		ArgumentNullException.ThrowIfNull(sink);
+		switch (_state)
+		{
+			case State.Tag or State.Quoted:
+				Abandon('<', sink);
+				break;
+			case State.Entity:
+				Abandon('&', sink);
+				break;
+			case State.Comment:
+				// A comment may run over lines; it waits for its end.
+				return;
+		}
+	}
+
+	/// <summary>Forgets what is half read.</summary>
+	public void Reset()
+	{
+		_pending.Clear();
+		_state = State.Text;
+	}
+
+	private string Take()
+	{
+		var taken = _pending.ToString();
+		_pending.Clear();
+		return taken;
+	}
+
+	private void Abandon(char opener, ITagSink sink)
+	{
+		var text = opener + Take();
+		_state = State.Text;
+		sink.Text(text);
+	}
+}
diff --git a/MarkupString/Decoding/TagSyntax.cs b/MarkupString/Decoding/TagSyntax.cs
new file mode 100644
index 0000000..6f45693
--- /dev/null
+++ b/MarkupString/Decoding/TagSyntax.cs
@@ -0,0 +1,181 @@
+namespace MarkupString.Decoding;
+
+/// <summary>One argument of a tag: <c>name=value</c>, <c>name</c> alone, or a value with no name.</summary>
+/// <param name="Name">The name, or null for a positional value.</param>
+/// <param name="Value">The value, unquoted; for a name alone, empty.</param>
+public readonly record struct TagArgument(string? Name, string Value);
+
+/// <summary>A tag as MXP and Pueblo write them: <c>&lt;name arg arg=value&gt;</c>, <c>&lt;/name&gt;</c> or <c>&lt;name/&gt;</c>.</summary>
+/// <param name="Name">The tag's name, as written.</param>
+/// <param name="Closing">Whether it is a closing tag.</param>
+/// <param name="Arguments">Its arguments, in order.</param>
+public sealed record ParsedTag(string Name, bool Closing, IReadOnlyList<TagArgument> Arguments)
+{
+	/// <summary>Whether it closes itself (<c>&lt;name/&gt;</c>).</summary>
+	public bool SelfClosing { get; init; }
+
+	/// <summary>
+	/// The argument named <paramref name="name"/>, ignoring case, or else the positional one at
+	/// <paramref name="position"/> (counting positional arguments only), or null.
+	/// </summary>
+	public string? Get(string name, int position = -1)
+	{
+		foreach (var argument in Arguments)
+		{
+			if (argument.Name is not null && argument.Name.Equals(name, StringComparison.OrdinalIgnoreCase)) return argument.Value;
+		}
+
+		if (position < 0) return null;
+		var at = 0;
+		foreach (var argument in Arguments)
+		{
+			if (argument.Name is not null) continue;
+			if (at++ == position) return argument.Value;
+		}
+
+		return null;
+	}
+
+	/// <summary>Whether a flag (a positional argument such as <c>PROMPT</c>) or a named argument is present.</summary>
+	public bool Has(string name)
+	{
+		foreach (var argument in Arguments)
+		{
+			if (string.Equals(argument.Name ?? argument.Value, name, StringComparison.OrdinalIgnoreCase)) return true;
+		}
+
+		return false;
+	}
+}
+
+/// <summary>Reads tags and entities the way MXP and Pueblo write them.</summary>
+public static class TagSyntax
+{
+	/// <summary>
+	/// Parses what is between <c>&lt;</c> and <c>&gt;</c>. Values may be quoted with <c>"</c> or <c>'</c>; entities in them
+	/// are decoded with <paramref name="entity"/> when it is given.
+	/// </summary>
+	public static ParsedTag? Parse(ReadOnlySpan<char> body, Func<string, string?>? entity = null)
+	{
+		body = body.Trim();
+		var closing = false;
+		var selfClosing = false;
+		if (body.StartsWith('/'))
+		{
+			closing = true;
+			body = body[1..].TrimStart();
+		}
+
+		if (body.EndsWith('/'))
+		{
+			selfClosing = true;
+			body = body[..^1].TrimEnd();
+		}
+
+		var nameEnd = 0;
+		while (nameEnd < body.Length && !char.IsWhiteSpace(body[nameEnd])) nameEnd++;
+		if (nameEnd == 0) return null;
+		var name = body[..nameEnd].ToString();
+		var rest = body[nameEnd..];
+
+		var arguments = new List<TagArgument>();
+		while (true)
+		{
+			rest = rest.TrimStart();
+			if (rest.IsEmpty) break;
+
+			string? argumentName = null;
+			if (rest[0] is not ('"' or '\''))
+			{
+				var end = 0;
+				while (end < rest.Length && !char.IsWhiteSpace(rest[end]) && rest[end] != '=') end++;
+				var word = rest[..end].ToString();
+				rest = rest[end..].TrimStart();
+				if (rest.IsEmpty || rest[0] != '=')
+				{
+					arguments.Add(new TagArgument(null, Decode(word, entity)));
+					continue;
+				}
+
+				argumentName = word;
+				rest = rest[1..].TrimStart();
+			}
+
+			string value;
+			if (!rest.IsEmpty && rest[0] is '"' or '\'')
+			{
+				var close = rest[1..].IndexOf(rest[0]);
+				value = close < 0 ? rest[1..].ToString() : rest.Slice(1, close).ToString();
+				rest = close < 0 ? [] : rest[(close + 2)..];
+			}
+			else
+			{
+				var end = 0;
+				while (end < rest.Length && !char.IsWhiteSpace(rest[end])) end++;
+				value = rest[..end].ToString();
+				rest = rest[end..];
+			}
+
+			arguments.Add(new TagArgument(argumentName, Decode(value, entity)));
+		}
+
+		return new ParsedTag(name, closing, arguments) { SelfClosing = selfClosing };
+	}
+
+	/// <summary>
+	/// The text an entity name (what is between <c>&amp;</c> and <c>;</c>) stands for: a number (<c>#65</c>,
+	/// <c>#x41</c>), one of HTML's, or what <paramref name="entity"/> returns; null when it is none of those.
+	/// </summary>
+	public static string? Entity(ReadOnlySpan<char> name, Func<string, string?>? entity = null)
+	{
+		if (name.IsEmpty) return null;
+		if (name[0] == '#')
+		{
+			var number = name[1..];
+			var hex = !number.IsEmpty && number[0] is 'x' or 'X';
+			if (hex) number = number[1..];
+			if (!int.TryParse(number, hex ? System.Globalization.NumberStyles.AllowHexSpecifier : System.Globalization.NumberStyles.None,
+				System.Globalization.CultureInfo.InvariantCulture, out var code)) return null;
+			if (code is <= 0 or > 0x10FFFF || (code is >= 0xD800 and <= 0xDFFF)) return null;
+			// A control character from an entity would reach the screen as a control; it is dropped.
+			if (code < 0x20 && code != '\t') return string.Empty;
+			return char.ConvertFromUtf32(code);
+		}
+
+		if (entity?.Invoke(name.ToString()) is { } defined) return defined;
+		var raw = $"&{name};";
+		var decoded = System.Net.WebUtility.HtmlDecode(raw);
+		return decoded == raw ? null : decoded;
+	}
+
+	/// <summary><paramref name="text"/> with its entities decoded; one that is not known is left as it is.</summary>
+	public static string Decode(string text, Func<string, string?>? entity = null)
+	{
+		var amp = text.IndexOf('&');
+		if (amp < 0) return text;
+
+		var result = new System.Text.StringBuilder(text.Length);
+		var at = 0;
+		while (amp >= 0)
+		{
+			var semicolon = text.IndexOf(';', amp + 1);
+			if (semicolon < 0 || semicolon - amp > 32) break;
+			var decoded = Entity(text.AsSpan(amp + 1, semicolon - amp - 1), entity);
+			result.Append(text, at, amp - at);
+			if (decoded is null)
+			{
+				result.Append(text, amp, semicolon - amp + 1);
+			}
+			else
+			{
+				result.Append(decoded);
+			}
+
+			at = semicolon + 1;
+			amp = text.IndexOf('&', at);
+		}
+
+		result.Append(text, at, text.Length - at);
+		return result.ToString();
+	}
+}
diff --git a/MarkupString/PublicAPI.Unshipped.txt b/MarkupString/PublicAPI.Unshipped.txt
index fbf8ea7..a02de20 100644
--- a/MarkupString/PublicAPI.Unshipped.txt
+++ b/MarkupString/PublicAPI.Unshipped.txt
@@ -673,3 +673,56 @@ MarkupString.Decoding.DecodeDiagnostics.LimitsReached.set -> void
 MarkupString.Decoding.DecodeDiagnostics.PicturesFailed.set -> void
 MarkupString.Decoding.DecodeDiagnostics.UnhandledControls.set -> void
 MarkupString.Decoding.DecodeDiagnostics.UnhandledSequences.set -> void
+MarkupString.Decoding.ITagSink
+MarkupString.Decoding.ITagSink.Entity(System.ReadOnlySpan<char> name) -> void
+MarkupString.Decoding.ITagSink.ReadsMarkup.get -> bool
+MarkupString.Decoding.ITagSink.Tag(System.ReadOnlySpan<char> body) -> void
+MarkupString.Decoding.ITagSink.Text(System.ReadOnlySpan<char> text) -> void
+MarkupString.Decoding.ParsedTag
+MarkupString.Decoding.ParsedTag.<Clone>$() -> MarkupString.Decoding.ParsedTag!
+MarkupString.Decoding.ParsedTag.Arguments.get -> System.Collections.Generic.IReadOnlyList<MarkupString.Decoding.TagArgument>!
+MarkupString.Decoding.ParsedTag.Arguments.init -> void
+MarkupString.Decoding.ParsedTag.Closing.get -> bool
+MarkupString.Decoding.ParsedTag.Closing.init -> void
+MarkupString.Decoding.ParsedTag.Deconstruct(out string! Name, out bool Closing, out System.Collections.Generic.IReadOnlyList<MarkupString.Decoding.TagArgument>! Arguments) -> void
+MarkupString.Decoding.ParsedTag.Equals(MarkupString.Decoding.ParsedTag? other) -> bool
+MarkupString.Decoding.ParsedTag.Get(string! name, int position = -1) -> string?
+MarkupString.Decoding.ParsedTag.Has(string! name) -> bool
+MarkupString.Decoding.ParsedTag.Name.get -> string!
+MarkupString.Decoding.ParsedTag.Name.init -> void
+MarkupString.Decoding.ParsedTag.ParsedTag(string! Name, bool Closing, System.Collections.Generic.IReadOnlyList<MarkupString.Decoding.TagArgument>! Arguments) -> void
+MarkupString.Decoding.ParsedTag.SelfClosing.get -> bool
+MarkupString.Decoding.ParsedTag.SelfClosing.init -> void
+MarkupString.Decoding.TagArgument
+MarkupString.Decoding.TagArgument.Deconstruct(out string? Name, out string! Value) -> void
+MarkupString.Decoding.TagArgument.Equals(MarkupString.Decoding.TagArgument other) -> bool
+MarkupString.Decoding.TagArgument.Name.get -> string?
+MarkupString.Decoding.TagArgument.Name.init -> void
+MarkupString.Decoding.TagArgument.TagArgument() -> void
+MarkupString.Decoding.TagArgument.TagArgument(string? Name, string! Value) -> void
+MarkupString.Decoding.TagArgument.Value.get -> string!
+MarkupString.Decoding.TagArgument.Value.init -> void
+MarkupString.Decoding.TagScanner
+MarkupString.Decoding.TagScanner.Feed(System.ReadOnlySpan<char> text, MarkupString.Decoding.ITagSink! sink) -> void
+MarkupString.Decoding.TagScanner.Flush(MarkupString.Decoding.ITagSink! sink) -> void
+MarkupString.Decoding.TagScanner.InMarkup.get -> bool
+MarkupString.Decoding.TagScanner.MaxEntityLength.get -> int
+MarkupString.Decoding.TagScanner.MaxEntityLength.init -> void
+MarkupString.Decoding.TagScanner.MaxTagLength.get -> int
+MarkupString.Decoding.TagScanner.MaxTagLength.init -> void
+MarkupString.Decoding.TagScanner.Reset() -> void
+MarkupString.Decoding.TagScanner.TagScanner() -> void
+MarkupString.Decoding.TagSyntax
+override MarkupString.Decoding.ParsedTag.Equals(object? obj) -> bool
+override MarkupString.Decoding.ParsedTag.GetHashCode() -> int
+override MarkupString.Decoding.ParsedTag.ToString() -> string!
+override MarkupString.Decoding.TagArgument.GetHashCode() -> int
+static MarkupString.Decoding.ParsedTag.operator !=(MarkupString.Decoding.ParsedTag? left, MarkupString.Decoding.ParsedTag? right) -> bool
+static MarkupString.Decoding.ParsedTag.operator ==(MarkupString.Decoding.ParsedTag? left, MarkupString.Decoding.ParsedTag? right) -> bool
+static MarkupString.Decoding.TagArgument.operator !=(MarkupString.Decoding.TagArgument left, MarkupString.Decoding.TagArgument right) -> bool
+static MarkupString.Decoding.TagArgument.operator ==(MarkupString.Decoding.TagArgument left, MarkupString.Decoding.TagArgument right) -> bool
+static MarkupString.Decoding.TagSyntax.Decode(string! text, System.Func<string!, string?>? entity = null) -> string!
+static MarkupString.Decoding.TagSyntax.Entity(System.ReadOnlySpan<char> name, System.Func<string!, string?>? entity = null) -> string?
+static MarkupString.Decoding.TagSyntax.Parse(System.ReadOnlySpan<char> body, System.Func<string!, string?>? entity = null) -> MarkupString.Decoding.ParsedTag?
+~override MarkupString.Decoding.TagArgument.Equals(object obj) -> bool
+~override MarkupString.Decoding.TagArgument.ToString() -> string

From 4140c9d240eb0a1793b10178f1a336b162487ac9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 22:07:44 +0000
Subject: [PATCH 10/19] Decode Pueblo

---
 .../Decoding/PuebloDecoding.cs                | 322 ++++++++++++++++++
 MarkupString.Pueblo/PublicAPI.Unshipped.txt   |   8 +
 .../Decoding/PuebloDecodingTests.cs           |  90 +++++
 MarkupString/Decoding/DecodeContext.cs        |   3 +
 MarkupString/PublicAPI.Unshipped.txt          |   1 +
 5 files changed, 424 insertions(+)
 create mode 100644 MarkupString.Pueblo/Decoding/PuebloDecoding.cs
 create mode 100644 MarkupString.Tests/Decoding/PuebloDecodingTests.cs

diff --git a/MarkupString.Pueblo/Decoding/PuebloDecoding.cs b/MarkupString.Pueblo/Decoding/PuebloDecoding.cs
new file mode 100644
index 0000000..e8e75b1
--- /dev/null
+++ b/MarkupString.Pueblo/Decoding/PuebloDecoding.cs
@@ -0,0 +1,322 @@
+using System.Globalization;
+using MarkupString.Ansi;
+using MarkupString.Decoding;
+namespace MarkupString.Pueblo.Decoding;
+
+/// <summary>Registers Pueblo decoding on a <see cref="DecoderRegistry"/>.</summary>
+public static class PuebloDecoding
+{
+	/// <summary>The name to pass <see cref="MarkupString.Decoding.Decoder.EnableProtocol(string)"/> once the server has said it speaks Pueblo.</summary>
+	public const string Protocol = "pueblo";
+
+	/// <summary>The registry with <see cref="PuebloPlugin"/>.</summary>
+	public static DecoderRegistry WithPueblo(this DecoderRegistry registry)
+	{
+		ArgumentNullException.ThrowIfNull(registry);
+		return registry.With(PuebloPlugin.Instance);
+	}
+
+	/// <summary>
+	/// Whether <paramref name="line"/> is a server's Pueblo greeting (<c>This world is Pueblo 1.10 Enhanced.</c>), after
+	/// which a client answers <c>PUEBLOCLIENT</c> and turns the protocol on.
+	/// </summary>
+	public static bool IsGreeting(string line) =>
+		line is not null && line.TrimStart().StartsWith("This world is Pueblo ", StringComparison.OrdinalIgnoreCase);
+}
+
+/// <summary>
+/// Pueblo as a text protocol: plain MUD text until the server sends <c>&lt;/xch_mudtext&gt;</c> (or
+/// <c>&lt;img xch_mode=html&gt;</c>), then HTML, in which line breaks are <c>&lt;br&gt;</c> and a bare line feed is
+/// whitespace, until <c>&lt;xch_mudtext&gt;</c>. ANSI inside it is read as ever.
+/// </summary>
+/// <remarks>
+/// Styles (<c>b</c>, <c>i</c>, <c>u</c>, <c>s</c>, <c>font color</c>) become <see cref="AnsiMarkup"/>; links
+/// (<c>a href</c>, <c>a xch_cmd</c>) a link on one; and <c>img</c>, <c>img xch_sound</c>, <c>xch_pane</c>,
+/// <c>xch_page</c>, <c>xch_prefetch</c>, <c>pre</c> and <c>xch_mudtext</c> the shared vocabulary.
+/// </remarks>
+public sealed class PuebloPlugin : IDecoderPlugin
+{
+	/// <summary>The one instance.</summary>
+	public static PuebloPlugin Instance { get; } = new();
+
+	private PuebloPlugin()
+	{
+	}
+
+	/// <inheritdoc/>
+	public string Name => "pueblo";
+
+	/// <inheritdoc/>
+	public void Register(DecoderBuilder builder)
+	{
+		ArgumentNullException.ThrowIfNull(builder);
+		builder
+			.TextProtocol(PuebloDecoding.Protocol, static () => new PuebloReader())
+			.OnControl('\n', static (_, context) =>
+			{
+				// In HTML a line feed is whitespace; <br> ends the line.
+				if (!context.IsActive(PuebloDecoding.Protocol)) return false;
+				var state = context.State<PuebloState>();
+				return state.Html && state.Preformatted == 0;
+			})
+			.OnControl('\r', static (_, context) =>
+			{
+				if (!context.IsActive(PuebloDecoding.Protocol)) return false;
+				var state = context.State<PuebloState>();
+				return state.Html && state.Preformatted == 0;
+			});
+	}
+}
+
+internal sealed class PuebloState
+{
+	public bool Html { get; set; }
+
+	public int Preformatted { get; set; }
+
+	public List<(string Name, IMarkup? First)> Open { get; } = [];
+
+	public IMarkup? Pane { get; set; }
+}
+
+internal sealed class PuebloReader : ITextProtocol, ITagSink
+{
+	private readonly TagScanner _scanner = new();
+	private DecodeContext? _context;
+
+	private DecodeContext Context => _context!;
+
+	private PuebloState State => Context.State<PuebloState>();
+
+	public bool ReadsMarkup => true;
+
+	public void Feed(ReadOnlySpan<char> text, DecodeContext context)
+	{
+		_context = context;
+		_scanner.Feed(text, this);
+	}
+
+	public void EndLine(DecodeContext context)
+	{
+		_context = context;
+		_scanner.Flush(this);
+	}
+
+	public void Reset(DecodeContext context)
+	{
+		_context = context;
+		_scanner.Reset();
+		var state = State;
+		// Close the earliest of what this protocol opened, which closes the rest.
+		var ours = state.Open.Select(element => element.First).Append(state.Pane).OfType<IMarkup>().ToHashSet(ReferenceEqualityComparer.Instance);
+		var first = context.Elements.FirstOrDefault(ours.Contains);
+		if (first is not null) context.Close(first);
+		state.Open.Clear();
+		state.Pane = null;
+		state.Html = false;
+		state.Preformatted = 0;
+	}
+
+	public void Text(ReadOnlySpan<char> text) => Context.Print(text);
+
+	public void Entity(ReadOnlySpan<char> name)
+	{
+		var decoded = State.Html ? TagSyntax.Entity(name) : null;
+		Context.Print(decoded ?? $"&{name};");
+	}
+
+	public void Tag(ReadOnlySpan<char> body)
+	{
+		var state = State;
+		var tag = TagSyntax.Parse(body, static name => null);
+		var name = tag?.Name.ToLowerInvariant();
+
+		if (name == "xch_mudtext")
+		{
+			if (tag!.Closing)
+			{
+				state.Html = true;
+				Close("xch_mudtext");
+			}
+			else
+			{
+				state.Html = false;
+				OpenElement("xch_mudtext", PreformattedMarkup.Instance);
+			}
+
+			return;
+		}
+
+		if (name == "img" && tag!.Get("xch_mode") is { } mode)
+		{
+			state.Html = mode.Equals("html", StringComparison.OrdinalIgnoreCase) || mode.Equals("purehtml", StringComparison.OrdinalIgnoreCase);
+			return;
+		}
+
+		if (!state.Html || tag is null)
+		{
+			// MUD text: what looks like a tag is text.
+			Context.Print($"<{body}>");
+			return;
+		}
+
+		if (tag.Closing)
+		{
+			if (name == "pre" && state.Preformatted > 0) state.Preformatted--;
+			Close(name!);
+			return;
+		}
+
+		if (!Element(tag, name!)) Context.Diagnostics.UnhandledSequences++;
+	}
+
+	private bool Element(ParsedTag tag, string name)
+	{
+		var context = Context;
+		switch (name)
+		{
+			case "b" or "strong":
+				OpenStyle(name, new AnsiStyle { Bold = true });
+				return true;
+			case "i" or "em":
+				OpenStyle(name, new AnsiStyle { Italic = true });
+				return true;
+			case "u":
+				OpenStyle(name, new AnsiStyle { Underlined = true });
+				return true;
+			case "s" or "strike" or "del":
+				OpenStyle(name, new AnsiStyle { StrikeThrough = true });
+				return true;
+			case "font":
+				OpenStyle(name, new AnsiStyle { Foreground = Color(tag.Get("color")), Background = Color(tag.Get("bgcolor")) });
+				return true;
+			case "a":
+				{
+					AnsiStyle? link = null;
+					var hint = tag.Get("xch_hint");
+					if (tag.Get("xch_cmd") is { Length: > 0 } command)
+					{
+						link = new AnsiStyle { LinkUrl = command, LinkKind = LinkKind.Command, LinkText = hint };
+					}
+					else if (tag.Get("href") is { } href && UrlSafety.IsSafeNavigableUrl(href))
+					{
+						link = new AnsiStyle { LinkUrl = href, LinkKind = LinkKind.Url, LinkText = hint };
+					}
+
+					OpenElement(name, link is { } style ? new AnsiMarkup(style) : null);
+					return true;
+				}
+			case "br":
+				context.EndLine();
+				return true;
+			case "p" or "hr":
+				if (!context.LineIsEmpty) context.EndLine();
+				return true;
+			case "pre":
+				State.Preformatted++;
+				OpenElement(name, PreformattedMarkup.Instance);
+				return true;
+			case "img":
+				Image(tag);
+				return true;
+			case "xch_page":
+				if (string.Equals(tag.Get("clear"), "text", StringComparison.OrdinalIgnoreCase)) context.Point(ClearScreenMarkup.Instance);
+				return true;
+			case "xch_prefetch":
+				if (tag.Get("href") is { Length: > 0 } source) context.Point(new PrefetchMarkup(source));
+				return true;
+			case "xch_pane":
+				Pane(tag);
+				return true;
+			case "html" or "head" or "body" or "title" or "tt" or "small" or "big" or "center" or "span" or "div" or "nobr":
+				return true;
+			default:
+				return false;
+		}
+	}
+
+	private void Image(ParsedTag tag)
+	{
+		var context = Context;
+		if (tag.Get("xch_sound") is { } action)
+		{
+			var device = tag.Get("xch_device");
+			var channel = device is null ? (SoundChannel?)null
+				: device.Equals("midi", StringComparison.OrdinalIgnoreCase) ? SoundChannel.Music : SoundChannel.Effects;
+			if (action.Equals("stop", StringComparison.OrdinalIgnoreCase))
+			{
+				context.Point(new SoundStopMarkup(channel));
+				return;
+			}
+
+			if (tag.Get("href") is not { Length: > 0 } href) return;
+			int? volume = int.TryParse(tag.Get("xch_volume"), NumberStyles.None, CultureInfo.InvariantCulture, out var v) ? Math.Clamp(v, 0, 100) : null;
+			var loops = action.Equals("loop", StringComparison.OrdinalIgnoreCase);
+			context.Point(new SoundMarkup(href, channel ?? SoundChannel.Effects, volume, loops ? SoundMarkup.Forever : null));
+			return;
+		}
+
+		if (tag.Get("src") is not { Length: > 0 } src) return;
+		var alt = tag.Get("alt");
+		int? width = int.TryParse(tag.Get("width"), NumberStyles.None, CultureInfo.InvariantCulture, out var w) && w > 0 ? w : null;
+		int? height = int.TryParse(tag.Get("height"), NumberStyles.None, CultureInfo.InvariantCulture, out var h) && h > 0 ? h : null;
+		var align = Enum.TryParse<ImageAlign>(tag.Get("align"), ignoreCase: true, out var parsed) ? parsed : (ImageAlign?)null;
+		var image = new ImageMarkup(src, string.IsNullOrEmpty(alt) ? null : alt, width, height, align);
+		context.Write(string.IsNullOrEmpty(alt) ? " " : alt, image);
+	}
+
+	private void Pane(ParsedTag tag)
+	{
+		if (!string.Equals(tag.Get("action"), "redirect", StringComparison.OrdinalIgnoreCase)) return;
+		var state = State;
+		if (state.Pane is { } current)
+		{
+			Context.Close(current);
+			state.Pane = null;
+		}
+
+		var name = tag.Get("name");
+		if (string.IsNullOrEmpty(name) || name.StartsWith('_')) return;
+		var pane = new PaneMarkup(name, tag.Get("panetitle"));
+		if (Context.Open(pane)) state.Pane = pane;
+	}
+
+	private void OpenStyle(string name, AnsiStyle style) => OpenElement(name, style.IsNone ? null : new AnsiMarkup(style));
+
+	private void OpenElement(string name, IMarkup? markup)
+	{
+		if (markup is not null && !Context.Open(markup)) markup = null;
+		State.Open.Add((name, markup));
+	}
+
+	private void Close(string name)
+	{
+		var open = State.Open;
+		var index = open.FindLastIndex(element => element.Name == name);
+		if (index < 0) return;
+		for (var i = index; i < open.Count; i++)
+		{
+			if (open[i].First is { } first)
+			{
+				Context.Close(first);
+				break;
+			}
+		}
+
+		open.RemoveRange(index, open.Count - index);
+	}
+
+	private static AnsiColor? Color(string? name)
+	{
+		if (string.IsNullOrWhiteSpace(name)) return null;
+		name = name.Trim();
+		if (name[0] == '#' && name.Length == 7
+			&& int.TryParse(name.AsSpan(1), NumberStyles.AllowHexSpecifier, CultureInfo.InvariantCulture, out var value))
+		{
+			return new AnsiColor.Rgb((byte)(value >> 16), (byte)(value >> 8), (byte)value);
+		}
+
+		var known = System.Drawing.Color.FromName(name);
+		return known.IsKnownColor && !known.IsSystemColor ? new AnsiColor.Rgb(known.R, known.G, known.B) : null;
+	}
+}
diff --git a/MarkupString.Pueblo/PublicAPI.Unshipped.txt b/MarkupString.Pueblo/PublicAPI.Unshipped.txt
index 7dc5c58..ec744c5 100644
--- a/MarkupString.Pueblo/PublicAPI.Unshipped.txt
+++ b/MarkupString.Pueblo/PublicAPI.Unshipped.txt
@@ -1 +1,9 @@
 #nullable enable
+MarkupString.Pueblo.Decoding.PuebloDecoding
+MarkupString.Pueblo.Decoding.PuebloPlugin
+MarkupString.Pueblo.Decoding.PuebloPlugin.Name.get -> string!
+MarkupString.Pueblo.Decoding.PuebloPlugin.Register(MarkupString.Decoding.DecoderBuilder! builder) -> void
+const MarkupString.Pueblo.Decoding.PuebloDecoding.Protocol = "pueblo" -> string!
+static MarkupString.Pueblo.Decoding.PuebloDecoding.IsGreeting(string! line) -> bool
+static MarkupString.Pueblo.Decoding.PuebloDecoding.WithPueblo(this MarkupString.Decoding.DecoderRegistry! registry) -> MarkupString.Decoding.DecoderRegistry!
+static MarkupString.Pueblo.Decoding.PuebloPlugin.Instance.get -> MarkupString.Pueblo.Decoding.PuebloPlugin!
diff --git a/MarkupString.Tests/Decoding/PuebloDecodingTests.cs b/MarkupString.Tests/Decoding/PuebloDecodingTests.cs
new file mode 100644
index 0000000..54c2ca5
--- /dev/null
+++ b/MarkupString.Tests/Decoding/PuebloDecodingTests.cs
@@ -0,0 +1,90 @@
+using MarkupString.Ansi;
+using MarkupString.Ansi.Decoding;
+using MarkupString.Decoding;
+using MarkupString.Display;
+using MarkupString.Html;
+using MarkupString.Pueblo;
+using MarkupString.Pueblo.Decoding;
+
+public class PuebloDecodingTests
+{
+	private static readonly DecoderRegistry Registry = VtDecoding.Terminal.WithPueblo();
+
+	private static List<DisplayLine> Decode(string text)
+	{
+		var decoder = Registry.CreateDecoder();
+		decoder.EnableProtocol(PuebloDecoding.Protocol);
+		var lines = new List<DisplayLine>(decoder.Feed(text));
+		if (decoder.HasPendingLine) lines.Add(decoder.EndLine());
+		return lines;
+	}
+
+	private static IReadOnlyList<DisplaySpan> Spans(DisplayLine line) => SpanRenderer.Render(line.Content, AnsiDisplay.Default, new DisplayOptions());
+
+	private static IEnumerable<IMarkup> Markups(DisplayLine line) => line.Content.Runs.SelectMany(run => run.Markups);
+
+	[Test]
+	public async Task MudText_TagsAreText()
+	{
+		var lines = Decode("<b>x</b>\n");
+		await Assert.That(lines[0].Content.ToPlainText()).IsEqualTo("<b>x</b>");
+	}
+
+	[Test]
+	public async Task Html_BreaksAtBr_NotAtLineFeeds()
+	{
+		var lines = Decode("</xch_mudtext>one<BR>\ntwo\nstill two<br>\n");
+		await Assert.That(lines.Select(line => line.Content.ToPlainText())).IsEquivalentTo(["one", "twostill two"]);
+	}
+
+	[Test]
+	public async Task Html_StylesAndLinks()
+	{
+		var lines = Decode("</xch_mudtext><b>bold</b> <a xch_cmd=\"look\" xch_hint=\"Look\">look</a> <a href=\"https://example.com\">site</a><br>");
+		var spans = Spans(lines[0]);
+		await Assert.That(spans[0].Style.Has(TextAttributes.Bold)).IsTrue();
+		await Assert.That(spans[2].Style.Interaction).IsEqualTo(new Interaction(InteractionKind.Command, "look") { Hint = "Look" });
+		await Assert.That(spans[4].Style.Interaction).IsEqualTo(new Interaction(InteractionKind.Url, "https://example.com"));
+	}
+
+	[Test]
+	public async Task Html_Entities()
+	{
+		var lines = Decode("</xch_mudtext>a &lt;b&gt; &amp;&nbsp;c<br>");
+		await Assert.That(lines[0].Content.ToPlainText()).IsEqualTo("a <b> & c");
+	}
+
+	[Test]
+	public async Task MudTextRegion_KeepsItsLines()
+	{
+		var lines = Decode("</xch_mudtext><xch_mudtext>a\nb\n</xch_mudtext>c<br>");
+		await Assert.That(lines.Select(line => line.Content.ToPlainText())).IsEquivalentTo(["a", "b", "c"]);
+		await Assert.That(Markups(lines[0]).Contains(PreformattedMarkup.Instance)).IsTrue();
+	}
+
+	[Test]
+	public async Task WhatThisPackageWrites_ReadsBack()
+	{
+		var registry = MarkupRegistry.Empty.WithAnsi().WithHtml().WithPueblo();
+		var link = MarkupText.Wrap(new AnsiMarkup(new AnsiStyle { LinkUrl = "look", LinkKind = LinkKind.Command, LinkText = "Look" }), "look");
+		var text = MarkupText.Concat([
+			MarkupText.Sound("https://example.test/door.wav", volume: 80),
+			MarkupText.Pane(MarkupText.Concat([MarkupText.Plain("North: "), link]), "map", "The Map"),
+			MarkupText.Plain("\nnext & last")]);
+		var wire = text.Render(MarkupFormat.Pueblo, registry);
+
+		var lines = Decode("</xch_mudtext>" + wire);
+		await Assert.That(lines.Select(line => line.Content.ToPlainText())).IsEquivalentTo(["North: look", "next & last"]);
+		await Assert.That(Markups(lines[0]).OfType<SoundMarkup>().Single()).IsEqualTo(new SoundMarkup("https://example.test/door.wav", Volume: 80));
+		await Assert.That(Markups(lines[0]).OfType<PaneMarkup>().First()).IsEqualTo(new PaneMarkup("map", "The Map"));
+		await Assert.That(Spans(lines[0])[^1].Style.Interaction).IsEqualTo(new Interaction(InteractionKind.Command, "look") { Hint = "Look" });
+		await Assert.That(Markups(lines[1]).OfType<PaneMarkup>().Any()).IsFalse();
+	}
+
+	[Test]
+	public async Task Greeting()
+	{
+		await Assert.That(PuebloDecoding.IsGreeting("This world is Pueblo 1.10 Enhanced.")).IsTrue();
+		await Assert.That(PuebloDecoding.IsGreeting("Welcome!")).IsFalse();
+	}
+}
diff --git a/MarkupString/Decoding/DecodeContext.cs b/MarkupString/Decoding/DecodeContext.cs
index 800b851..47fcc34 100644
--- a/MarkupString/Decoding/DecodeContext.cs
+++ b/MarkupString/Decoding/DecodeContext.cs
@@ -46,6 +46,9 @@ internal DecodeContext(Decoder decoder)
 	/// <summary>The pane the lines being read are for, or null for the main output.</summary>
 	public string? Destination { get; set; }
 
+	/// <summary>Whether nothing has been written to the current line.</summary>
+	public bool LineIsEmpty => Line.IsEmpty;
+
 	/// <summary>The column the next character is written at, in cells.</summary>
 	public int Column => Line.Cursor;
 
diff --git a/MarkupString/PublicAPI.Unshipped.txt b/MarkupString/PublicAPI.Unshipped.txt
index a02de20..ae04b24 100644
--- a/MarkupString/PublicAPI.Unshipped.txt
+++ b/MarkupString/PublicAPI.Unshipped.txt
@@ -726,3 +726,4 @@ static MarkupString.Decoding.TagSyntax.Entity(System.ReadOnlySpan<char> name, Sy
 static MarkupString.Decoding.TagSyntax.Parse(System.ReadOnlySpan<char> body, System.Func<string!, string?>? entity = null) -> MarkupString.Decoding.ParsedTag?
 ~override MarkupString.Decoding.TagArgument.Equals(object obj) -> bool
 ~override MarkupString.Decoding.TagArgument.ToString() -> string
+MarkupString.Decoding.DecodeContext.LineIsEmpty.get -> bool

From 5bb2972dbc141a1d255e9f48cc1d1c51b58d2153 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 22:08:33 +0000
Subject: [PATCH 11/19] Document pictures, MXP and Pueblo decoding

---
 docs/decoding.md | 144 +++++++++++++++++++++++++++++++++++++++++++++--
 docs/display.md  |   4 +-
 2 files changed, 141 insertions(+), 7 deletions(-)

diff --git a/docs/decoding.md b/docs/decoding.md
index 31c0620..e8631b4 100644
--- a/docs/decoding.md
+++ b/docs/decoding.md
@@ -178,7 +178,7 @@ Decoder.DecodeAll("\e(0lqqk\e(B ok", registry)[0].Content;  // ┌──┐ ok
 | `110`, `111`, `112` | Reset them |
 | `52;sel;base64` | `ClipboardEvent` with the decoded text, or a null text for `?`. Invalid base64 is dropped. |
 | `8;params;uri` | A link over the text that follows, until an empty uri. An address longer than 2083 characters, or one `UrlSafety.IsSafeNavigableUrl` refuses (`javascript:` and the like), ends the link instead. |
-| `68;1;SEND;command` | An MSLP command link over the underlined text that follows. Turning the underline off ends it. |
+| `68;1;SEND;command` | An MSLP command link over the underlined text that follows. Turning the underline off ends it, and so does the end of the line. |
 
 Colours are X11 specs: `rgb:r/g/b` with one to four hex digits a channel, or `#rgb`, `#rrggbb`,
 `#rrrgggbbb`, `#rrrrggggbbbb`. `OscPlugin.ParseColor` and `FormatColor` are public. Links are
@@ -210,9 +210,11 @@ place. A progress bar redrawn over itself ends as its last state.
 | `hello world\r\e[Kbye` | `bye` |
 | `a\tb` | `a       b` |
 | `a\e[10Gb` | `a        b` |
+| `漢字\rX` | `X 字` |
 
 Moving the cursor past the end of the line pads with spaces only when text follows, so a tab at the
-end of a line leaves no trailing blanks. The style of overwritten cells is replaced with the new text's.
+end of a line leaves no trailing blanks. The style of overwritten cells is replaced with the new text's. A wide character that is only partly
+overwritten is blanked where it is not covered, as a terminal blanks it.
 
 ## Limits and diagnostics
 
@@ -233,7 +235,7 @@ so a bare `ESC ]` typed into a channel cannot swallow the rest of the session.
 | Property | Default | |
 |---|---|---|
 | `MaxOpenElements` | 64 | Elements a text protocol may have open at once |
-| `MaxLineLength` | 65536 | Characters in a line. Text that would take the line past it is dropped. |
+| `MaxLineLength` | 65536 | Characters in a line. A longer line is ended at the limit and the rest starts the next line. |
 
 `decoder.Diagnostics` counts what was dropped:
 
@@ -245,7 +247,7 @@ decoder.Feed("\e[?25lHello\e]0;never closed\nworld\u0001\n");
 // UnhandledControls  = 1   U+0001
 ```
 
-`LimitsReached` counts text and elements dropped at a limit. `PicturesFailed` counts pictures that
+`LimitsReached` counts lines broken at the limit and elements refused. `PicturesFailed` counts pictures that
 could not be decoded.
 
 ## Client identity and answers
@@ -460,6 +462,136 @@ The SGR reset inside the element ends the red pen, not the bold element. `EndLin
 element left open, so the next line starts plain. `EnableProtocol` returns false when the registry
 offers no protocol of that name; `ActiveProtocol` names the one that is on.
 
-## Pictures, MXP and Pueblo
+## Pictures
 
-These plugins are covered in their own sections.
+`WithPictures()` adds `PicturesPlugin`, which reads Kitty graphics (`APC G`), iTerm2 inline images
+(`OSC 1337 File=`, and `MultipartFile=`/`FilePart=`/`FileEnd`) and sixel (`DCS q`). Each picture
+becomes an `ImageMarkup` over the cells it covers, one `PictureRow` per line, so a cell renderer
+draws it and the ANSI writer can send it on to another terminal in whatever way that terminal
+draws pictures. Kitty to Kitty, sixel to Kitty, and iTerm2 to half blocks all go through the same
+markup.
+
+```csharp
+var registry = DecoderRegistry.Empty.WithVt().WithPictures();
+var decoder = registry.CreateDecoder(new DecoderOptions
+{
+    Identity = new ClientIdentity { CellWidth = 8, CellHeight = 16, Columns = 100 },
+});
+
+var lines = decoder.Feed(wire);
+var store = decoder.Pictures();                       // this connection's PictureStore
+foreach (var image in lines.SelectMany(l => l.Content.Runs).SelectMany(r => r.Markups).OfType<ImageMarkup>())
+{
+    if (store.TryGet(image, out var picture)) Console.WriteLine($"{picture.Width}x{picture.Height} {picture.MediaType}");
+}
+```
+
+The pixels live in the decoder's `PictureStore`, and an image's `Source` is `picture:` and a key
+(a hash of the picture, so the same picture sent twice is stored once). The store:
+
+- keeps `Budget` bytes (64 MiB), dropping the least recently used first. A line whose picture is gone
+  shows its text instead.
+- refuses a picture of more than `MaxPixels` (4096 × 4096).
+- is the `ITerminalPictureSource` to give `AnsiOutputOptions.Pictures`, so decoded pictures can be
+  written to a terminal again.
+- gives `StoredPicture.ToDataUrl()` for an `<img>`, and raises `Added` so a host can serve pictures
+  from its own address instead.
+
+PNG and sixel are decoded here, and Kitty's raw RGB and RGBA, zlib-compressed or not. A GIF, JPEG or
+WebP sent as an iTerm2 image is kept as the file with no pixels: a browser shows it, a terminal gets
+its text.
+
+A picture's size in cells comes from its pixels and `ClientIdentity.CellWidth` and `CellHeight`,
+unless the sequence says otherwise (Kitty `c` and `r`, iTerm2 `width` and `height` in cells, `px`
+or `%`). It is never wider than `ClientIdentity.Columns`.
+
+Placement follows the terminal: the first row beside the text already on the line, each further row
+on its own line, the cursor below the picture afterwards. A picture drawn between `ESC 7` and
+`ESC 8`, or Kitty's `C=1`, is drawn over the lines that follow instead, which is how a server writes
+a picture beside text and how this package's own ANSI writer sends iTerm2 and sixel pictures.
+
+Kitty specifics:
+
+- Only `t=d` (the picture in the sequence) is read. A file, temporary file or shared memory is
+  refused with `EINVAL`, since the server's files are not the client's.
+- `a=t`, `a=T`, `a=p`, `a=q` and `a=d` are read; animation frames are not, so a moving picture is its
+  first frame.
+- Unicode placeholders (U+10EEEE with row and column diacritics, the image id in the foreground
+  colour) draw a picture transmitted with `U=1`. That is how this package's writer sends Kitty
+  pictures, so its output reads back cell for cell.
+- Replies (`\e_Gi=…;OK\e\\`) follow `q` and need `ClientAnswers.Pictures`. A picture sent with
+  neither `i` nor `I` gets none.
+
+An iTerm2 file with `inline=0` is not shown: a `DownloadEvent` says it was offered. Nothing is saved.
+
+## MXP
+
+`MarkupString.Mxp` adds `WithMxp()` for a `DecoderRegistry`. MXP is a text protocol, off until the
+host turns it on after telnet negotiates option 91:
+
+```csharp
+using MarkupString.Mxp.Decoding;
+
+var registry = DecoderRegistry.Empty.WithVt().WithMxp();
+var decoder = registry.CreateDecoder();
+decoder.EnableProtocol(MxpDecoding.Protocol);
+
+decoder.Feed("\e[1z<SEND href=\"buy sword|look sword\" hint=\"Sword|Buy|Look\">sword</SEND>\n");
+```
+
+Line modes (`ESC [ n z`) decide what a line may use. Until MXP is on they are claimed and ignored.
+
+| Mode | |
+|---|---|
+| `0`, `1`, `2` | This line is open, secure or locked |
+| `3` | Close every MXP element and go back to open |
+| `4` | The next tag is secure |
+| `5`, `6`, `7` | Open, secure or locked from now on |
+| `10`, `11`, `12`, `19` | This line is a room name, description, exits or welcome text: an `MxpFlagMarkup` over it |
+| `20`–`99` | This line is the element the server tied to that number with `TAG=` |
+
+On an open line only the open tags work: `B`, `I`, `U`, `S`, `H`, `C`/`COLOR`, `FONT`, `BR`, `SBR`,
+`P`, `NOBR`. A secure tag there is dropped and counted in `UnhandledSequences`. On a locked line `<`
+and `&` are text. Elements opened on an open line close at its end.
+
+What the tags become:
+
+| Tag | Markup |
+|---|---|
+| `B`, `I`, `U`, `S`, `H`, `COLOR`, `FONT` | An `AnsiMarkup`. SGR inside an MXP colour wins, as in an MXP client. |
+| `A href hint` | A URL link, when `UrlSafety` allows the address |
+| `SEND href hint prompt` | A command link. With several commands (`a\|b`) or `PROMPT`, a `CommandMenuMarkup` as well. With no `href`, or `&text;` in it, the command is the tag's text. |
+| `IMAGE fname url w h align` | An `ImageMarkup`. Sized in cells (`W=4c H=2c`), it is drawn over the cells the server leaves for it. |
+| `SOUND`, `MUSIC` | `SoundMarkup` or `SoundStopMarkup` points |
+| `FRAME`, `DEST` | A `PaneMarkup` over the text in `DEST`, titled from its `FRAME` |
+| `VAR name` | A `VariableMarkup` over its text, and a `VariableEvent` |
+| `EXPIRE`, `RELOCATE`, `USER`, `PASSWORD` | Their points |
+| `VERSION`, `SUPPORT` | Answered (`\e[1z<VERSION …>`, `\e[1z<SUPPORTS +send …>`) when `ClientAnswers.Mxp` allows |
+
+`<!ELEMENT>` defines an element from other tags, with `ATT` attributes substituted for `&name;`,
+`FLAG` for an `MxpFlagMarkup`, `OPEN`, `EMPTY` and `TAG`. `<!ENTITY>` defines an entity, used as
+`&name;` and published as a `VariableEvent` unless `PRIVATE`. `<!ATTLIST>` and `<!TAG>` are read
+too. To serialise lines with `MxpFlagMarkup`, add `MxpDecoding.FlagCodec` to the `MarkupRegistry`.
+
+What `MarkupFormat.Mxp` writes reads back to the same markup.
+
+## Pueblo
+
+`MarkupString.Pueblo` adds `WithPueblo()`. Turn the protocol on when the server greets the client
+(`PuebloDecoding.IsGreeting(line)`) and the client has answered `PUEBLOCLIENT`.
+
+The server starts in MUD text, where tags are text. `</xch_mudtext>` or `<img xch_mode=html>`
+switches to HTML, where a line ends at `<br>` and a bare line feed is whitespace; `<xch_mudtext>`
+switches back, and its region is a `PreformattedMarkup`. ANSI is read in both.
+
+| Tag | Markup |
+|---|---|
+| `b`, `i`, `u`, `s`, `font color` | An `AnsiMarkup` |
+| `a xch_cmd xch_hint`, `a href` | A command or URL link |
+| `img src alt` | An `ImageMarkup` over the alt text |
+| `img xch_sound=play\|loop\|stop href xch_volume` | `SoundMarkup` or `SoundStopMarkup` |
+| `xch_pane action=redirect name panetitle` | A `PaneMarkup` until the next redirect |
+| `xch_page clear=text`, `xch_prefetch href` | `ClearScreenMarkup`, `PrefetchMarkup` |
+| `br`, `p`, `hr`, `pre` | Line breaks, and a `PreformattedMarkup` for `pre` |
+
+What `MarkupFormat.Pueblo` writes reads back to the same markup.
diff --git a/docs/display.md b/docs/display.md
index f9518d6..57163dc 100644
--- a/docs/display.md
+++ b/docs/display.md
@@ -179,6 +179,7 @@ var text = Decoder.DecodeAll("\e[31mred\e[0m \e[34;44msame\e[0m", decoders)[0].C
 - **Colours.** At `ColorLevel.Attributes` or `None` both colours are dropped. Above that, every colour
   is already RGB, so the level does not reduce it further here.
 - **Attributes.** Those the output lacks are dropped. At `ColorLevel.None` every attribute is.
+- **Prompts.** A `CommandMenuMarkup` with `Prompt` set is a `Prompt` interaction.
 - **Inverse.** With colour, foreground and background are swapped, filling in `DefaultForeground` and
   `DefaultBackground`; `Inverse` stays set for information. At `Attributes` the flag is kept for the
   output to draw when it has `TextAttributes.Inverse`, and dropped when it does not.
@@ -228,7 +229,7 @@ and `Point` set. Text no markup covers is `DisplayStyle.Plain`.
 
 `SpanRenderer.Css(style)` is inline CSS: `color`, `background-color`, `font-weight:bold`,
 `opacity:0.6` for faint, `font-style:italic`, `text-decoration` for underline, overline and
-line-through, and `color:transparent` for conceal. `CssClasses(style)` gives the classes a page
+line-through, and `color:transparent` for conceal, in place of the text's colour. `CssClasses(style)` gives the classes a page
 styles itself:
 
 | Class | When |
@@ -238,6 +239,7 @@ styles itself:
 | `ms-link`, `ms-command`, `ms-prompt` | The interaction's kind |
 | `ms-menu` | An interaction with more than one choice |
 | `ms-picture` | A picture |
+| `ms-invert` | Inverse with no colours to swap, at `ColorLevel.Attributes`; `AnsiCss.Fixed` styles it |
 
 `SpanRenderer.Hex(color)` writes `#rrggbb`.
 

From 00e6d606587ec6e90c6475b5334034edc31fa9de Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 22:08:50 +0000
Subject: [PATCH 12/19] Remove the display pipeline design and plan; add
 changelog entry

---
 CHANGELOG.md                                  |  29 ++
 .../plans/2026-11-06-display-pipeline.md      | 451 ----------------
 .../2026-11-06-display-pipeline-design.md     | 490 ------------------
 3 files changed, 29 insertions(+), 941 deletions(-)
 delete mode 100644 docs/superpowers/plans/2026-11-06-display-pipeline.md
 delete mode 100644 docs/superpowers/specs/2026-11-06-display-pipeline-design.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1cd79cb..75f1364 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,35 @@ and `MarkupString.Pueblo`. The packages share one version and are released toget
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
 follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Added
+
+- **Decoding server output.** `MarkupString.Decoding` reads what a server sends into `MarkupText` lines: a VT
+  tokenizer, a `DecoderRegistry` of plugins (`IDecoderPlugin`, handlers tried newest first), and a `Decoder` per
+  connection with `Feed`, `EndLine` and `EndPrompt`. Carriage return, backspace and erase overwrite in place, so a
+  progress bar ends as its last state. Titles, palette changes, the clipboard, variables and replies to send back
+  are `DecodeEvent`s; `ClientIdentity` says what the client answers, and `ToMtts` gives its MTTS bits. See
+  [Decoding](docs/decoding.md).
+- **Terminal plugins** in `MarkupString.Ansi.Decoding`: `WithVt()` reads SGR (colon subparameters included),
+  the C0 controls, the DEC special graphics set, OSC 8 and MSLP links, titles, palette, clipboard, and answers
+  device attributes, XTVERSION, size and colour queries. The cursor position is not answered unless the host
+  allows it.
+- **Pictures**: `WithPictures()` reads Kitty graphics (placeholders included), iTerm2 inline images and sixel into
+  `ImageMarkup` rows, with PNG and sixel decoders and a per-connection `PictureStore` that is also the
+  `ITerminalPictureSource` to write them out again. What the ANSI writer sends reads back cell for cell.
+- **MXP and Pueblo decoding**: `WithMxp()` in `MarkupString.Mxp` (line modes, open and secure tags, `SEND`
+  menus, custom elements, entities, `VERSION` and `SUPPORT`) and `WithPueblo()` in `MarkupString.Pueblo`. What
+  each package writes reads back to the same markup. `MarkupString.Mxp` now depends on `MarkupString.Ansi`.
+- **Display.** `MarkupString.Display` resolves markup to RGB styles for an output, degraded to its
+  `OutputCapabilities`: `SpanRenderer` for a web page (spans, inline CSS, classes) and `CellRenderer` for a cell
+  grid (wide characters, tabs, wrapping, picture cells, hit testing). `DisplayRegistry.Core.WithAnsi()` folds
+  terminal styles; `TerminalProfile.ToOutputCapabilities` and `ToTerminalFeatures` convert between the two
+  models. See [Display](docs/display.md).
+- `CommandMenuMarkup` (a menu of commands, or a prompt) and `HighlightMarkup` (a background) in core, with codecs.
+- `AnsiStyle.Concealed` (SGR 8), written as SGR 8 and as `ms-conceal` in HTML.
+- `PictureRow.FirstColumn`, for a picture row shown from a column other than its first.
+
 ## 2.25.0 — 2026-11-02
 
 ### Changed
diff --git a/docs/superpowers/plans/2026-11-06-display-pipeline.md b/docs/superpowers/plans/2026-11-06-display-pipeline.md
deleted file mode 100644
index 9b744f8..0000000
--- a/docs/superpowers/plans/2026-11-06-display-pipeline.md
+++ /dev/null
@@ -1,451 +0,0 @@
-# Display pipeline: conversion plan
-
-**Goal:** Every protocol a game sends (ANSI and its extensions first, then MXP and Pueblo) reaches every output a
-SharpMUSH client draws on (an outer terminal, a cell grid, web components, an HTML string) as the best thing that
-output can show, through one decoder and one model.
-
-**Spec:** `docs/superpowers/specs/2026-11-06-display-pipeline-design.md`. This plan works out the conversions the spec
-leaves open, in particular pictures, and orders the work.
-
-**Status:** accepted 2026-11-06.
-
-## 1. The rule: decode, never pass through
-
-The tempting shortcut for "Kitty in, Kitty out" is to copy the sequence to the outer terminal. That breaks:
-
-| Why passthrough fails | Where it shows |
-|---|---|
-| Image ids collide. The server numbers its images; so does the client (SharpMUTerm hands out ids from `0xC00000`, and SharpConsoleUI numbers its own) and so does `TerminalPictureWriter.KittyId`. | A game's image 1 replaces the client's map. |
-| A placement is drawn at the server's idea of the cursor. The client's cursor is in a pane, in a layout, under a header. | The picture lands on the input line or a sidebar. |
-| Scrollback reflows. A pane resized after the picture arrived moves the text but not a placed picture. | Pictures float over the wrong lines. Only Unicode placeholders survive this, because they are text. |
-| The outer terminal is not the one the server was told about. The client advertised its own capabilities; the outer terminal may be a different one, or tmux. | Sixel printed as garbage in Alacritty. |
-| `t=f`, `t=t` and `t=s` tell the terminal to read a local file or shared memory object. Passed through, the server reads the player's disk. | Security hole. |
-| Queries (`a=q`, DA1, `CSI 16 t`) are answered by the outer terminal, but its reply arrives on the client's input stream, which SharpConsoleUI owns. | Replies lost, or typed into the command line. |
-
-So every sequence ends at the decoder, becomes model, and each target writes its own output from the model. The
-one optimisation allowed is *encoded passthrough*: a picture that arrived as PNG bytes can be sent to an output
-that takes PNG (Kitty `f=100`, iTerm2, a browser) without decoding the pixels. That reuses the bytes; it never
-reuses the sequence.
-
-```text
- source sequence ──► decoder plugin ──► model (MarkupText + PictureStore + events) ──► target encoder ──► output
-   Kitty APC          kitty                ImageMarkup{Row} over blank cells             Kitty placeholders
-   sixel DCS          sixel                + PictureAsset(key, pixels | bytes | url)     sixel / iTerm2 / ▀▄
-   MXP <IMAGE>        mxp                                                                Skia bitmap
-   …                                                                                     <img src=blob/data/url>
-```
-
-## 2. Targets
-
-Five targets. They differ in who owns the screen and what they can draw, and a client may use more than one
-(SharpMUTerm has T1 and T3; the portal has T5).
-
-| Id | Target | Example | Owns interaction | Pictures as | Colour |
-|---|---|---|---|---|---|
-| T1 | Outer terminal, client owns the screen | SharpMUTerm TUI inside kitty, Windows Terminal | client (mouse reporting) | Kitty placeholders, iTerm2 inline, sixel, half blocks, chosen by `TerminalProfile` | by profile |
-| T2 | Dumb ANSI sink | a log file, `cat` of a capture, a proxy to a telnet user | the terminal, if anything | as T1 but only what that terminal reads, usually none | `AnsiColorDepth` |
-| T3 | Cell grid drawn by the client | SharpMUTerm window (`CellGrid` + Skia) | client (hit test) | bitmap slices in cells | truecolor |
-| T4 | Web components | SharpClient `OutputView` | client (`@onclick`) | `<img>` from URL, blob or data URI | truecolor via CSS |
-| T5 | HTML string | SharpMUSH portal `TerminalLine.Html` | page script (`xch_cmd`) | `<img>` as T4 | truecolor via CSS |
-
-T2 is MarkupString's existing `MarkupFormat.Ansi` output and needs nothing new beyond the picture source.
-
-## 3. Conversion tables
-
-Each cell says what the target receives. "Text" means the fallback text the decoder kept under the markup: alt
-text for a picture, the label for a link. Nothing in a cell is ever dropped without leaving its text.
-
-### 3.1 Pictures
-
-| Source | T1 Kitty | T1 iTerm2 / sixel | T1 blocks only | T2 | T3 | T4 / T5 |
-|---|---|---|---|---|---|---|
-| Kitty transmit and display (`a=T`, direct `t=d`, `f=24/32/100`, `o=z`, chunked `m=1`) | placeholders, retransmitted once under the client's id | encoded by `TerminalPictureWriter` | half blocks | as T1 for its profile | bitmap | PNG (encoded passthrough for `f=100`, `PngWriter` for raw) |
-| Kitty transmit (`a=t`) then put (`a=p`, `i`/`p`, `c`/`r`) | as above, at the put | as above | as above | as above | as above | as above |
-| Kitty virtual placement (`U=1`) plus `U+10EEEE` placeholder text | placeholder cells re-keyed to the client's id; the picture is already text-shaped | the same rows, drawn | half blocks | as T1 | bitmap slices | `<img>` over the rows' box; a cropped placement is a CSS `object-position` crop |
-| Kitty animation (`a=f` frames, `a=a`) | frames, if `MovingPictures` | iTerm2 GIF if `MovingPictures`; else first frame | first frame | as T1 | frames (host animates) | animated GIF via `GifWriter`, or first frame |
-| Kitty delete (`a=d`, lower or upper case) | see [3.1.3](#313-delete-and-replace) | | | | | |
-| Kitty query (`a=q`) | answered per [section 5](#5-what-the-client-answers) | | | | | |
-| Kitty `t=f`, `t=t`, `t=s` | refused with an error reply; nothing read | | | | | |
-| Sixel (`DCS P1;P2;P3 q … ST`) | decoded to pixels, then as Kitty direct | iTerm2 PNG, or sixel re-encoded at the client's size and palette | half blocks | as T1 | bitmap | PNG |
-| iTerm2 inline (`OSC 1337 ; File=inline=1;… : base64`, single or `MultipartFile`/`FilePart`/`FileEnd`) | Kitty `f=100` when PNG, else decoded | iTerm2: original bytes; sixel: decoded | half blocks | as T1 | bitmap (host decodes) | original bytes as blob or data URI, when the browser reads the type |
-| iTerm2 download (`inline=0`) | never saved; `DownloadOffered` event with name and size, text "[file: name]" | | | | | |
-| MXP `<IMAGE>` (URL + FName, `W`/`H` in px, `c` or `%`, `ALIGN`) | fetched by the host, decoded, then as Kitty direct | as left | half blocks | text | bitmap | `<img src>` with the address itself, after `UrlSafety`; no fetch by the client code |
-| Pueblo / HTML `<img src>` | as MXP | as MXP | as MXP | text | bitmap | as MXP |
-| Half-block, quadrant, sextant or braille art (plain text) | text | text | text | text | text; T3 draws block elements as shapes, as `CellRenderer` already does | text in a monospace span |
-
-Text art is never upgraded to a picture. It is text the server chose; its colours go through the colour table.
-
-#### 3.1.1 Where a picture sits in a line model
-
-All five targets are line-oriented scrollback, not a fixed screen. A picture placed at the cursor becomes rows of
-blank cells under `ImageMarkup { Row = PictureRow(i, rows, columns) }`, which is how MarkupString's `Figure` already
-reserves space, so every target that can draw it draws it and every other one shows the cells' text.
-
-| Source placement | Becomes |
-|---|---|
-| Cursor at the start of a line, picture `r` rows tall | `r` lines, each `columns` blank cells under the picture's row `i` |
-| Cursor mid-line at column `x` (Kitty `C=0`: the spec moves the cursor right by `c` and down by `r`) | the text before it ends its line; then the `r` rows; the cursor is then column `x + c` of a new line below them, so text that follows starts there after blank cells, and a line with nothing written stays empty, as it would on kitty's screen |
-| Kitty `C=1` (cursor does not move) | as above, but on kitty the text that follows overprints the picture; a line model cannot overprint, so it goes below the picture and the line gets an `Overlapped` flag |
-| Sixel (cursor ends on the line below the picture, or to its right with private mode 8452) | below: a new line at column 0. Right of the last row (8452): text there would sit beside the picture, which the line model cannot hold, so it also starts a new line, with the `Overlapped` flag |
-| Unicode placeholders | already cells: each run of `U+10EEEE` becomes blanks under `ImageMarkup.Row`, with its row and starting column read from the diacritics |
-| MXP / Pueblo image in running text | as "cursor mid-line"; an image with no size until fetched is a one-row label (its alt text) until the host has the size, then a `PictureSized` event lets the client re-lay that line |
-
-The last row is what SharpMUTerm already does with `InlineImageHost` (rows inserted under the line once the
-picture is fetched); the plan moves that logic into the shared picture service.
-
-`PictureRow` needs one new field for placeholders that show part of a picture: `FirstColumn`, the column of the
-picture the run starts at (Kitty lets a placement be cropped, and a run of placeholders can start at any
-column).
-
-#### 3.1.2 Sizing
-
-Cells are what matter in every target but T4/T5, and the source and the target can disagree about how many pixels
-a cell is.
-
-1. A size the source gave in cells (Kitty `c`/`r`, iTerm2 `width=N`, MXP `W=Nc`) is kept: the server laid text
-   out around it.
-2. Else a size in pixels (Kitty `s`/`v` or the image's own, iTerm2 `Npx`, MXP `W=N`) is turned into cells with
-   the *target's* cell metrics.
-3. A percentage (iTerm2 `N%`, MXP `W=N%`) is a share of the pane's columns, or of a row cap for height, as
-   SharpMUTerm's `InlineImageLayout` does.
-4. The result keeps the picture's aspect unless the source said otherwise (iTerm2 `preserveAspectRatio=0`, MXP
-   both `W` and `H`), then shrinks to fit the pane width and a maximum height (SharpMUTerm uses 24 rows).
-
-Cell metrics, per target: T1 asks the outer terminal (`CSI 16 t`) where the host can read the reply, else assumes
-8×16, the 1:2 ratio SharpMUTerm chose because it keeps a square picture square under both Kitty and half blocks.
-T3 takes them from its font. T4/T5 measure one monospace cell in CSS and fall back to 8×16; the picture itself
-is sized in CSS pixels with `max-width: 100%`.
-
-Pixels are never stretched past the source's resolution unless the source asked for a larger box.
-
-#### 3.1.3 Delete and replace
-
-A terminal is one screen; a client has scrollback. Kitty's delete means "take it off the screen", and for a
-history that is ambiguous. The decoder raises `PictureWithdrawn(key, freeData)` and the client chooses:
-
-| Policy | Effect | Default for |
-|---|---|---|
-| `KeepInHistory` | old lines keep the picture; uppercase delete only frees it when the store's byte budget needs the room, after which old lines show their text | all clients |
-| `ReplaceInPlace` | a new picture under the same server id and placement id replaces the old one wherever it is shown | a pane or status area, later |
-| `Remove` | lines that showed it show their text from now on | opt-in |
-
-The store never reuses a key. Retransmitting under the same server id gives a new generation
-(`{connection}/kitty/{id}/{generation}`), so caches and Kitty ids derived from the key cannot show stale pixels.
-
-#### 3.1.4 Decoding and fetching
-
-MarkupString stays free of image libraries. It ships what the terminal protocols need, and the host supplies the
-rest:
-
-| Format | Who decodes | Note |
-|---|---|---|
-| Raw RGB/RGBA (Kitty `f=24/32`), zlib (`o=z`) | MarkupString (`System.IO.Compression`) | inflate is capped at `s × v × bytes-per-pixel` |
-| PNG | MarkupString, new small decoder | Kitty `f=100` is the common case; PNG is fully specified and needs only zlib |
-| GIF | MarkupString, new decoder next to `GifWriter` | for iTerm2 and animation |
-| Sixel | MarkupString, new decoder next to `SixelWriter` | HLS and RGB colour registers, repeat, raster attributes, `P2=1` transparent background |
-| JPEG, WebP, anything else | host `IPictureDecoder` | SharpMUTerm: StbImageSharp plus ImageSharp's WebP module (its `ImageDecoder`); Avalonia: Skia; browser: not needed |
-
-Header sniffing (PNG `IHDR`, GIF logical screen, JPEG `SOF`, WebP `VP8`/`VP8L`/`VP8X`) gives the size without
-decoding, so a line can be laid out at once and the pixels decoded off the parse thread.
-
-Fetching a URL is always the host's (`IPictureFetcher`), because it reveals the player's address and needs the
-rules SharpMUTerm's `WebImageLoader` has: http(s) and `data:` only, an image content type, a byte cap, a timeout,
-two concurrent fetches, a queue cap.
-
-#### 3.1.5 The picture store
-
-```csharp
-public sealed class PictureAsset
-{
-    public string Key { get; }                         // never reused
-    public PictureOrigin Origin { get; }               // Inline (bytes arrived in band) or Address (a URL)
-    public string? Address { get; }
-    public PictureSize? NaturalSize { get; }           // pixels, from the header or the source
-    public PictureState State { get; }                 // Declared, Received, Decoded, Failed, Released
-}
-
-public interface IPictureStore : ITerminalPictureSource // so the existing ANSI writers draw from it unchanged
-{
-    PictureAsset Declare(PictureDeclaration declaration);
-    bool TryGetEncoded(string key, out ReadOnlyMemory<byte> bytes, out string mediaType);
-    bool TryGetPixels(string key, [NotNullWhen(true)] out TerminalPicture? picture);
-    event Action<PictureAsset>? Changed;               // Decoded, Sized, Released: the client repaints
-}
-```
-
-One store per session, with an LRU byte budget for pixels and one for encoded bytes, and one picture larger than
-the budget used once and not kept, as `InlineImageHost` does. A decoded in-band picture's `ImageMarkup.Source` is
-`picture:{key}`; MarkupString's HTML emitter currently writes `Source` into `src` as is, so it gains an
-`IPictureAddressProvider` option that turns `picture:` keys into a blob URL or a data URI, and refuses to write a
-`picture:` address it cannot resolve.
-
-### 3.2 Colour
-
-| Source | T1 / T2 | T3 | T4 / T5 |
-|---|---|---|---|
-| SGR 30–37, 90–97, 40–47, 100–107 | kept as standard colours, so the outer terminal's own palette shows them | theme palette (`IColorResolver`) | theme palette as CSS variables (`AnsiCss`) |
-| `38;5;n`, `48;5;n` | at the profile's depth (`AnsiStyle.AtDepth`) | resolved through the xterm table | resolved |
-| `38;2;r;g;b` and `38:2::r:g:b` | at the profile's depth (redmean nearest) | as given | as given |
-| SGR 39, 49 (default) | default | the theme's default | the theme's default |
-| OSC 4 (set palette entry), OSC 104 (reset) | the connection's palette override; standard colours that it redefines are written as RGB so the outer terminal's palette is not changed | override applied in the resolver | override applied |
-| OSC 10/11/12 set default fg/bg/cursor | ignored by default (a player's theme wins), opt-in per world | | |
-| Contrast floor | — | `Contrast.Legible` against the plane, as SharpMUTerm's `MarkupFormatter` does today | same function, so all clients agree |
-
-A palette change never touches the outer terminal. That is the server reaching past the client into the player's
-terminal, which the client exists to mediate.
-
-### 3.3 Attributes
-
-| SGR | T1 / T2 | T3 | T4 / T5 |
-|---|---|---|---|
-| 1 bold, 2 faint, 3 italic, 9 strike, 53 overline | as is, if the profile has them | font weight/style, decorations | CSS |
-| 4 underline; `4:2` double, `4:3` curly, `4:4` dotted, `4:5` dashed; 21 double | the kind if the profile has it, else 4 | decoration kind | `text-decoration-style` |
-| 58/59 underline colour | if supported, else dropped | decoration colour | `text-decoration-color` |
-| 5/6 blink | the player's setting (SharpMUTerm "allow blink"), default off | same | `ms-blink` class, off unless the page turns it on |
-| 7 inverse | inverse | colours swapped at resolve time | colours swapped at resolve time |
-| 8 conceal | conceal | foreground drawn as background; text still selectable and searchable | `color: transparent` |
-| 22–29, 55 off codes | as given | | |
-
-### 3.4 Links and commands
-
-| Source | T1 | T2 | T3 | T4 | T5 |
-|---|---|---|---|---|---|
-| OSC 8 URL (with `id`) | client hit test; also OSC 8 to the outer terminal when the profile has `Hyperlinks`, so its own hover and open work | OSC 8 if `Hyperlinks`, else text | interaction in the cell table, grouped by `id` for hover | `<a href>` after `UrlSafety` | `<a href>` |
-| MXP `<A HREF>`, Pueblo `<A HREF>`, HTML `<a>` | as OSC 8 | as OSC 8 | as OSC 8 | as OSC 8 | as OSC 8 |
-| MXP `<SEND>`, Pueblo `XCH_CMD`, MSLP (`OSC 68`) | client hit test sends the command; never written as MSLP to the outer terminal, which would send it nowhere | MSLP if the sink advertised it, else text | interaction | `<button>` | `ms-cmd-link` with `xch_cmd` |
-| MXP `<SEND PROMPT>` | puts the text in the command line | text | interaction | `<button>` that fills the input | as T4 |
-| MXP `<SEND href="a|b">` menu | context menu | first choice, or text | menu | menu | `ms-cmd-menu` with the choices as data |
-| MXP `<EXPIRE>` | links in that group stop being clickable and keep their text | | | | |
-| A command link from an MXP open line | never made: it is literal text (the security rule in the spec) | | | | |
-
-### 3.5 Sound and attention
-
-| Source | T1 | T2 | T3 | T4 / T5 |
-|---|---|---|---|---|
-| BEL | `BellMarkup` point; the client's attention setting decides, and BEL reaches the outer terminal only if the player allows it | BEL | client's setting | `ms-bell` |
-| MXP `<SOUND>`, `<MUSIC>`, Pueblo `xch_sound` | host audio (SharpMUTerm.Audio) through `IPictureFetcher`'s rules for the file | nothing | host audio | `<audio preload="none">` |
-| MSP `!!SOUND(…)` text triggers | not decoded in v1; a later plugin can claim the text | | | |
-
-### 3.6 Screen controls
-
-These decide whether the line model holds. Everything here is decoded, and nothing is forwarded.
-
-| Source | Line model (default) | Screen tier (opt-in, later) |
-|---|---|---|
-| LF | ends the line (the telnet layer usually ended it already) | cursor down |
-| CR without LF | column 0 of the current line; following text overwrites cells, so a progress bar redraws in place | as a terminal |
-| BS | one cell left; next character overwrites (`a BS _` overstrike is not turned into underline) | as a terminal |
-| HT | kept as a tab; renderers expand to 8 with `TextLayout` | tab stops |
-| FF, `CSI 2 J`, `CSI H CSI J` | `ClearScreenMarkup` point; the client decides (the portal already styles `ms-clear`) | clear |
-| `CSI K` (erase in line) | clears the current line from the cursor, in the line builder | as a terminal |
-| Cursor moves `CUU/CUD/CUF/CUB/CUP`, `DECSTBM`, `?1049h` alternate screen | dropped, as all three clients do today; counted in diagnostics | drive a `ScreenBuffer` |
-| `ESC ( 0` / `ESC ) 0` DEC special graphics, `SO`/`SI` | mapped to Unicode box drawing, so old MUD maps draw | same |
-| OSC 0/2 title | `TitleChanged` event; never forwarded | same |
-| OSC 52 clipboard | `ClipboardRequest` event; refused unless the player allows that world | same |
-| DCS/APC/PM/SOS nobody claimed | consumed, capped, dropped | same |
-
-### 3.7 Structure
-
-| Source | Model | Targets |
-|---|---|---|
-| Telnet GA / EOR (from the host) | `DisplayLine.Kind = Prompt` | SharpMUTerm prompt row, portal prompt row |
-| MXP `<FRAME>` / `<DEST>`, Pueblo `xch_pane` | `PaneMarkup` / `DisplayLine.Destination`, `FrameOpened` events | client pane; a target without panes shows the text in the main view |
-| MXP room tags (`ESC [10z`–`12z`, `<RName>`, `<RDesc>`, `<RExits>`) | `RoomPartMarkup` data layer | invisible; read by SharpMUTerm's `MxpRoomSource` |
-| MXP `<VAR>`, `<GAUGE>`, `<STAT>`, `<!ENTITY>` | `VariableMarkup`, `GaugeMarkup`, `StatusMarkup`, `VariableSet` events | client gauges; else text |
-| MXP `<RELOCATE>`, `<USER>`, `<PASSWORD>` | the existing vocabulary points, raised as events | the client asks the player; never automatic |
-
-## 4. Capabilities
-
-```csharp
-public sealed record OutputCapabilities
-{
-    public AnsiColorDepth Colors { get; init; }
-    public TextAttributes Attributes { get; init; }
-    public UnderlineKinds Underlines { get; init; }
-    public InteractionKinds Interactions { get; init; }    // Url, Command, Prompt, Menu
-    public PictureMethods Pictures { get; init; }          // Bitmap, KittyPlaceholders, InlineImage, Sixel, HalfBlocks
-    public bool MovingPictures { get; init; }
-    public bool Sound { get; init; }
-    public bool Panes { get; init; }
-    public UnicodeLevel Unicode { get; init; }             // Full, NoWide, Ascii
-    public CellMetrics? Cell { get; init; }
-
-    public static OutputCapabilities FromTerminal(TerminalProfile profile, TerminalFeatures chosen, AnsiColorDepth depth);
-    public static OutputCapabilities CellGrid { get; }     // T3
-    public static OutputCapabilities Browser { get; }      // T4, T5
-}
-```
-
-`FromTerminal` maps `TerminalFeatures` one to one (`KittyGraphics` → `KittyPlaceholders`, and so on), so the
-terminal knowledge already in `TerminalProfile` is the only place it lives. A client that shows output in two
-places at once (a T1 pane and a T3 window over the same session) negotiates with the server on the union and
-renders each target with its own capabilities; the decoder's output is the same for both.
-
-`Effective = output ∩ what the decoder can read ∩ what the player turned on`. Pictures count as available when the
-output can draw *some* picture method better than text, because the decoder transcodes: a client in Alacritty
-(half blocks only) can still advertise Kitty input, receive a picture and show it as half blocks. Whether
-half blocks are worth asking for is the player's choice (`PictureFloor`: off, half blocks, native only).
-
-## 5. What the client answers
-
-A server learns what to send by asking. The decoder answers as the virtual terminal the client presents, built
-from `Effective`, and sends nothing a host has not turned on.
-
-| Server sends | Answer | Built from |
-|---|---|---|
-| Telnet TTYPE cycle | client name, then a terminal name, then `MTTS n` | `ToMtts`: 1 ANSI, 2 VT100, 4 UTF-8, 8 256 colours, 32 OSC colour palette, 64 screen reader, 256 truecolor, 1024 MSLP, from `Effective`; sent by the telnet layer |
-| MXP `<SUPPORT tags>` | `<SUPPORTS +B +COLOR -IMAGE …>` on a secure line | the MXP plugin's handlers ∩ `Effective` (no `+IMAGE` without pictures) |
-| MXP `<VERSION>` | `<VERSION MXP=1.0 STYLE=… CLIENT=… VERSION=…>` | host strings |
-| Kitty `a=q` (and feature query `e=`) | `OK` for `t=d` with the formats the store decodes; error for `t=f/t/s`; nothing when `q=2`, no `OK` when `q=1` | `Effective.Pictures` and the decoder list |
-| DA1 `CSI c` | `CSI ? 62 ; 22 c`, plus `; 4` when sixel input is on | decoder list |
-| XTVERSION `CSI > q` | `DCS > | ClientName Version ST` | host strings |
-| `CSI 14 t`, `16 t`, `18 t` | text area pixels, cell pixels, rows and columns of the pane | target cell metrics and pane size |
-| `CSI 6 n` (cursor position) | the pane's last row, the current line's column + 1 | line builder |
-| OSC 10/11 `?` | the theme's default foreground/background as `rgb:rrrr/gggg/bbbb` | `IColorResolver` |
-| Pueblo `This world is Pueblo …` | `PUEBLOCLIENT` with the md5, by the telnet layer | host |
-
-Answers leave through `DecodeEvent.ReplyToServer`; the decoder never writes to the socket. Each answer has a
-switch, and the defaults are on for MXP, Kitty and the size queries and off for cursor position, since a server
-that relies on it assumes a full screen.
-
-## 6. Security limits
-
-Defaults, all configurable in `DecodePolicy`:
-
-| Limit | Default | Why |
-|---|---|---|
-| CSI parameters | 32 | `vte`'s limit |
-| OSC payload, other than pictures | 4 KiB | OSC 8 URIs are capped at 2083 bytes by VTE and iTerm2 |
-| One picture, encoded | 16 MiB | a large PNG; iTerm2 caps one sequence at 1 MiB, mintty at about 4.4 MB |
-| One picture, decoded | 4096 × 4096 and 64 MiB of pixels | a zlib or PNG bomb stops at the cap |
-| Chunked transfers open at once | 4 | a server cannot hold memory with half-sent images |
-| Pictures per line | 8 | |
-| MXP element stack, definitions, entity depth | 64, 512, 8 | |
-| Tag, entity, escape sequence | 4096, 32, 128 chars | SharpMUTerm's current caps |
-
-Every limit hit drops the item, keeps its text, and counts it in diagnostics, so a player can tell why a picture
-did not show.
-
-## 7. Work plan
-
-Each task lists what it produces and when it is done. Tests are TUnit in `MarkupString.Tests`; new public API goes
-in `PublicAPI.Unshipped.txt`; each phase ends with a `CHANGELOG.md` entry and a minor version.
-
-### Phase 0: corpus and harness
-
-- **0.1 Capture corpus.** A folder of real sessions as raw text with line and prompt boundaries marked: PennMUSH,
-  TinyMUX, a Diku with MXP, a Pueblo world, a world sending Kitty or sixel (or a synthetic one), and the existing
-  fixtures from SharpMUTerm's and SharpClient's parser tests. Done when each file has a short note of where it came
-  from and what it exercises.
-- **0.2 Snapshot harness.** Feeds a corpus file through a decoder and writes approved snapshots of the decoded
-  lines (as MarkupString JSON), of cells, and of spans. Done when a changed snapshot fails the build.
-- **0.3 Chunking and fuzz harness.** Every case run whole and split at every index; a fuzzer over random bytes and
-  mutated corpus. Done when it runs in CI with a time budget.
-
-### Phase 1: VT decoding (MarkupString, MarkupString.Ansi)
-
-- **1.1 `VtTokenizer`** (Williams state machine, span based, stateful across `Feed`, `:` subparameters, every cap
-  in section 6, newline aborts a sequence). Tests: the state table, chunking, fuzz.
-- **1.2 Decoder core**: `DecoderRegistry`, `DecoderBuilder`, `DecodeContext`, newest-first dispatch with
-  fall-through, `DecodePolicy`, `DecodeEvent`, `DisplayLine`, `LineBuilder` with CR overwrite, BS, `CSI K`, `EndLine`,
-  `EndPrompt`.
-- **1.3 `vt` plugin**: full SGR, C0, DEC special graphics and `SO`/`SI`, clear screen as a point, title and
-  palette events, OSC 52 event.
-- **1.4 `osc8` and `mslp` plugins**, with `AnsiStyle.LinkId`.
-- **1.5 Vocabulary gaps** from the spec (conceal, underline kinds and colour, `LinkKind.Prompt`,
-  `CommandMenuMarkup`, `RoomPartMarkup`, `ElementFlagMarkup`, `HighlightMarkup`), with codecs, emitters where a
-  format has a spelling, and the JSON round trip.
-- **1.6 `AnsiEscapeParser.Parse`** on the decoder, its tests unchanged and passing.
-- **1.7 Round-trip property**: `Decode(Render(x, Ansi)) ≈ x` for generated `MarkupText`.
-
-Done when SharpMUTerm's `AnsiParser` tests and SharpClient's SGR tests, ported, pass against the decoder.
-
-### Phase 2: capabilities and answers
-
-- **2.1 `OutputCapabilities`** with `FromTerminal`, `CellGrid`, `Browser`; `Effective`.
-- **2.2 Answer builders**: `ToMtts`, DA1, XTVERSION, window and cell size, OSC 10/11, cursor position, each behind
-  a switch, raised as `ReplyToServer`.
-
-Done when a table test checks every answer in section 5 for three profiles (kitty, Alacritty, browser).
-
-### Phase 3: structured renderers (MarkupString, MarkupString.Ansi, MarkupString.Html)
-
-- **3.1 `DisplayStyle`, `IStyleContributor`, `IColorResolver`**, contributors for `AnsiMarkup`, `HtmlMarkup` and
-  the vocabulary; palette override from OSC 4.
-- **3.2 `SpanRenderer`** producing `DisplaySpan`s with `ms-*` classes.
-- **3.3 `CellRenderer`** (`Cell`, `ICellSurface`, layout through `TextLayout`, interaction table, hit test).
-- **3.4 Parity test**: one line as cells and as spans gives the same text, style runs and interaction ranges, over
-  the corpus.
-
-### Phase 4: pictures, model and outputs
-
-- **4.1 `PictureAsset`, `IPictureStore`** (budgets, keys, generations, `Changed`), implementing
-  `ITerminalPictureSource`.
-- **4.2 Decoders**: raw, zlib, PNG, GIF, header sniffers; `IPictureDecoder` and `IPictureFetcher` for the host.
-- **4.3 Sizing** (section 3.1.2), ported from `InlineImageLayout` with its tests.
-- **4.4 `PictureRow.FirstColumn`**, and the ANSI picture writers honouring it.
-- **4.5 Target encoders**: encoded passthrough to Kitty `f=100` and iTerm2; `IPictureAddressProvider` in the HTML
-  emitter and `SpanRenderer`; picture cells in `CellRenderer`.
-
-Done when a picture declared by hand reaches T1 (each method), T3, T4 and T5 from the same `MarkupText`, in snapshot
-tests.
-
-### Phase 5: picture protocols in (MarkupString.Ansi)
-
-- **5.1 `kitty` plugin**: actions `t`, `T`, `p`, `q`, `d`; `t=d` only; formats 24, 32, 100; `o=z`; chunking; ids
-  remapped to store keys; replies; placement to rows (section 3.1.1); `PictureWithdrawn`.
-- **5.2 Kitty placeholders in**: read `U+10EEEE` runs (image id from the foreground, third diacritic, placement id
-  from the underline colour, row and column inference), turn them into `ImageMarkup.Row` cells.
-- **5.3 `sixel` plugin**: decoder, placement, DA1 bit.
-- **5.4 `iterm-image` plugin**: single and multipart, units, `inline=0` as `DownloadOffered`.
-- **5.5 Kitty animation**: whole frames (`a=f` without composition) and `a=a` play and loop; anything else shows
-  the first frame.
-
-Done when each source row of table 3.1 has a snapshot test per target column.
-
-### Phase 6: MXP and Pueblo in (MarkupString.Mxp, MarkupString.Pueblo, MarkupString.Html)
-
-- **6.1 `TagTokenizer`** shared by all three.
-- **6.2 `mxp` plugin**, ported from SharpMUTerm's `MxpParser` and `MxpParser.Definitions` with their tests: line
-  modes, open and secure tags, definitions, entities, links and menus, frames, variables, gauges, room tags,
-  `SUPPORT` and `VERSION`, `<IMAGE>` and `<SOUND>` through the picture store and fetcher.
-- **6.3 `pueblo` plugin**, ported from `PuebloParser` with its tests.
-- **6.4 `html` plugin** through `HtmlTagPolicy`.
-- **6.5 Round trip** for `Mxp` and `Pueblo`, as 1.7.
-
-### Phase 7: consumers
-
-Each step is its own PR in that repository, behind a setting until the snapshots match.
-
-- **SharpMUTerm**: an `ILineParser` adapter over the decoder yielding `StyledLine`, swapped in for `AnsiParser`,
-  `MxpParser` and `PuebloParser` in `WorldSession`; then `InlineImageHost` on the picture store; then a SharpConsoleUI
-  emitter replacing `MarkupFormatter`; then window output panes on `CellRenderer`. The three parsers are deleted
-  once the adapter has shipped one release.
-- **SharpClient**: decoder in place of `AnsiParser` and `MxpParserState`; `OutputView` on `SpanRenderer`;
-  triggers on `DisplayLine` plain text.
-- **SharpMUSH portal**: plain-text frames decoded instead of ANSI-stripped; `IPictureAddressProvider` for pictures
-  that arrive in band.
-
-### Phase 8: later
-
-Kitty frame composition, the screen tier, MSP, MXP `ISMAP`, `ReplaceInPlace` panes.
-
-## 8. Risks
-
-| Risk | Mitigation |
-|---|---|
-| Ported MXP behaviour drifts from SharpMUTerm's during the move | port tests first; SharpMUTerm switches by setting and compares snapshots on the corpus before deleting its parser |
-| Kitty id collisions between the client's framework, the client and the writer's hash | a configurable id range on the output side (`KittyIds`), as `InlineImageHost.FirstKittyId` does now |
-| Re-laying a line when a fetched picture's size arrives moves the scrollback under the reader | only lines below the viewport's top are re-laid in place; a line above it keeps its label until scrolled to |
-| Decoding pictures on the parse thread stalls text | sniff on the thread, decode off it; text is never held for a picture |
-| Answering queries makes a server send things the player did not want | every answer is switchable and the picture floor is the player's |
-| Line model cannot show a server that draws a screen | counted in diagnostics; the screen tier is the answer, opt-in |
-
-## 9. Decisions needed
-
-1. Default delete policy: `KeepInHistory` (recommended) or `Remove`.
-2. Whether to answer `CSI 6 n` at all. Recommended off.
-3. Picture floor default: half blocks allowed (recommended, it is what SharpMUTerm does in Alacritty today) or native
-   only.
-4. Whether MarkupString ships the PNG, GIF and sixel decoders (recommended, needed for Kitty `f=100` and sixel
-   with no host library) or leaves all decoding to the host.
diff --git a/docs/superpowers/specs/2026-11-06-display-pipeline-design.md b/docs/superpowers/specs/2026-11-06-display-pipeline-design.md
deleted file mode 100644
index c832cd0..0000000
--- a/docs/superpowers/specs/2026-11-06-display-pipeline-design.md
+++ /dev/null
@@ -1,490 +0,0 @@
-# Display pipeline: decoding wire protocols and rendering them per output — design
-
-Status: accepted 2026-11-06. Nothing here is implemented yet.
-
-## Problem
-
-MarkupString renders one way: a `MarkupText` built on the server goes out as ANSI, HTML, MXP, Pueblo and the
-rest. Clients need the opposite direction. They receive a byte stream that mixes text, SGR, OSC, MXP or Pueblo
-tags and entities, and have to turn it into something they can draw: terminal cells, a cell grid drawn by
-Skia, or HTML spans in a browser.
-
-Each SharpMUSH client does this separately today, and none of them uses MarkupString to do it:
-
-| Client | Decode | Model | Draw |
-|---|---|---|---|
-| SharpMUTerm (`SharpMUTerm.Core`) | `AnsiParser`, `MxpParser` (2,260 lines with definitions), `PuebloParser` (786 lines), one per session picked by `ContentFormat` in `WorldSession` | `StyledLine` of `StyledSpan(Text, TextStyle, SpanInteraction?)` | TUI: `MarkupFormatter` turns a line into SharpConsoleUI markup (`[#rrggbb bold link=…]`), resolving colours through the theme and a contrast floor. Window: SharpConsoleUI writes into `CellGrid` (`GridCell(Rune, Combiners, Fg, Bg, Decorations, IsWideContinuation)`), and `CellRenderer` paints it with Skia, drawing Kitty placeholder cells (`U+10EEEE`) as picture slices. |
-| SharpClient (`SharpClient.Core.Rendering`) | `AnsiParser.Parse(line, MxpParserState?)`: SGR, MXP and Pueblo in one 591-line function set | `StyledSegment(Text, TextStyle){Command, Hint, ImageUrl}` | `OutputView.razor`: one `<span style>` per segment from `SegmentStyle.ToCss`, `<button>` for a command, `<img>` for a picture |
-| SharpMUSH portal (`SharpMUSH.Client`) | `TerminalFrameRenderer`: a `markup` frame is a serialized `MarkupText`; a non-envelope frame is plain text with "the legacy ANSI strip" | `MarkupText`, then `TerminalLine(Text, Html)` | `MarkupString` HTML renderer, written into the page as a raw HTML string per line |
-
-The SharpMUTerm source says the cost of this outright: its three escape state machines are "near-copies,
-deliberately not shared — a fix to one belongs in all three, with its own test in each suite". SharpClient has
-a fourth. Each has its own colour type, palette and style record, and each handles a different subset: SharpClient
-reads SGR 0, 1, 4, 7, 22, 24, 27 and colours, so italic, faint and strikethrough are lost; SharpMUTerm reads all of
-them and conceal.
-
-The portal is the exception that shows the way out. It already treats `MarkupText` as its display model, because
-SharpMUSH sends one. A client connected to any other game gets bytes, and needs a decoder that ends in the same
-model.
-
-## Goals
-
-1. One decoder for the wire, shared by all three clients, ending in `MarkupText`.
-2. Protocols as plugins: VT/SGR, OSC 8, MSLP, MXP, Pueblo, raw HTML, each registered on its own, so a client
-   takes only what it supports and a game can add its own.
-3. Renderers as plugins, with three first-class targets: an ANSI terminal, a cell grid, and web spans.
-4. Capability negotiation in both directions: what the client tells the server it can show, and how a renderer
-   degrades what it was sent to what its output can draw.
-5. Keep MarkupString's rules: immutable values, explicit registries, no reflection, Native AOT safe, a layer
-   nobody understands passes its text through.
-
-Non-goals: the telnet layer (option negotiation, MCCP, GMCP, charset). TelnetNegotiationCore owns it; the decoder
-starts after it, on decoded text. Full terminal emulation of full-screen programs is a later, optional tier
-(see [Screen tier](#screen-tier-optional)).
-
-## Prior art and what it settles
-
-| Source | What it settles here |
-|---|---|
-| Paul Williams' DEC ANSI parser state machine, as used by xterm.js (`EscapeSequenceParser`) and Rust `vte` (Alacritty) | Tokenize once with one state machine (ground, escape, CSI, OSC, DCS, SOS/PM/APC strings), and hand complete sequences to handlers. `vte`'s `Perform` trait is the shape: `print`, `execute`, `csi_dispatch`, `esc_dispatch`, `osc_dispatch`, `hook`/`put`/`unhook` for DCS. |
-| xterm.js parser hooks (`registerCsiHandler`, `registerOscHandler`, `registerDcsHandler`, `registerEscHandler`, `registerApcHandler`) | Plugins register by sequence identifier (`{prefix, intermediates, final}` for CSI/DCS, a number for OSC). Handlers are probed newest first; returning `false` passes the sequence on to older handlers, `true` stops. This is the plugin contract for escape sequences. |
-| OSC 8 ([egmontkob's spec](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda)) | `OSC 8 ; params ; URI ST`, closed by `OSC 8 ; ; ST`; params are `:`-separated `key=value`, only `id` defined. Cells with the same URI and non-empty `id` are one link for hover. VTE and iTerm2 cap the URI at 2083 bytes, VTE caps `id` at 250. The cell renderer's link id comes from here. |
-| MXP ([zuggsoft spec](https://www.zuggsoft.com/zmud/mxp.htm)) | Line modes are `ESC [ n z`: 0 open, 1 secure, 2 locked, 3 reset, 4 temp secure, 5–7 lock open/secure/locked, 10–12 room name/description/exits, 19 welcome, 20–99 user-defined. Only formatting tags (B, I, U, S, COLOR, H, FONT) are open; everything else is secure. `<SUPPORT>` is answered `<SUPPORTS +B -IMAGE …>` on a secure line. Line mode is a security boundary, so it belongs inside the MXP plugin, not in the renderer. |
-| Pueblo (as implemented in SharpMUTerm's `PuebloParser` and MarkupString's emitter) | HTML subset; command links are `<A XCH_CMD>`, URL links `<A HREF>`; `<xch_mudtext>` suspends `<BR>` line handling; enabling is a session handshake, not markup. |
-| Kitty graphics Unicode placeholders, and SharpMUTerm's `CellRenderer` | A picture can live in real text cells (`U+10EEEE`, image id in the foreground, row and column in combining marks), so it wraps, scrolls and clips like text. The cell model needs a picture-slice cell for this. |
-| MarkupString's own `TerminalProfile` / `TerminalFeatures` / `AnsiColorDepth` | The degrade ladder for a terminal already exists on the output side: Kitty → iTerm2 inline → sixel → half blocks → text; truecolor → 256 → 16 → attributes → none. Reuse it. |
-
-Lessons from the existing client parsers, which the shared decoder must keep (each is in SharpMUTerm's tests
-already):
-
-- The line boundary is what the host says it is. The telnet layer strips the terminator, so the decoder exposes
-  `EndLine()` and `EndPrompt()` (for GA/EOR) rather than waiting for `\n`.
-- A newline ends any escape sequence in flight. Otherwise a player typing a bare `ESC ]` into a channel swallows
-  the rest of the session.
-- Every buffer is capped: sequence, tag, entity, OSC payload.
-- When MXP leaves open mode, tags opened in open mode are closed. Otherwise `<COLOR FORE=black BACK=black>` in a
-  channel paints the rest of the session.
-- A secure MXP tag on an open line is literal text, so a player cannot make a `<SEND>` in someone else's client.
-- A stray `<` or `&` that cannot start a tag or entity is text.
-
-## Architecture
-
-```text
-            host (telnet layer, websocket)
-                      │  decoded text chunks, EndLine / EndPrompt, mode events (Pueblo on, MXP on)
-                      ▼
- ┌──────────────── Decoder (one per connection) ─────────────────┐
- │  VtTokenizer ──► sequence handlers (CSI / OSC / ESC / DCS / APC) │
- │       │ ground text                                             │
- │       ▼                                                         │
- │  TagTokenizer (only while an SGML protocol is active)           │
- │       └──► tag/entity handlers (MXP, Pueblo, HTML)              │
- │                         │ act on                                │
- │                  DecodeState: style, element stack, line mode   │
- │                         ▼                                       │
- │                  LineBuilder ──► DisplayLine(MarkupText, kind)  │
- └──────────────────────────┬──────────────────────────────────────┘
-                            │ DisplayLine stream + DecodeEvents (title, reply-to-server, variables, room, frames)
-                            ▼
-         scrollback, triggers, search, logging   (client-owned, on MarkupText)
-                            │
-            ┌───────────────┼──────────────────┐
-            ▼               ▼                  ▼
-     MarkupFormat.Ansi   CellRenderer       SpanRenderer / MarkupFormat.Html
-     (existing)          → ICellSurface     → DisplaySpan list or HTML string
-```
-
-Three parts, each with its own plugin point:
-
-1. **Decoder**: wire to `MarkupText`. Plugins are protocol handlers.
-2. **Display model**: `MarkupText` with the existing shared vocabulary, a few new markup kinds, and a
-   `DisplayLine` envelope.
-3. **Renderers**: model to output. Plugins are style contributors (how a markup kind looks) and renderers (what
-   the output is).
-
-### 1. Decoder
-
-#### Tokenizer
-
-One `VtTokenizer`, a Williams state machine over `ReadOnlySpan<char>`, kept across `Feed` calls so a sequence can
-straddle chunks. It emits tokens and never interprets them:
-
-```csharp
-public interface IVtTokenSink
-{
-    void Print(ReadOnlySpan<char> text);                       // ground text, one run at a time
-    void Execute(char control);                                // C0: BEL, BS, HT, CR, FF …
-    void Csi(in CsiSequence sequence);                         // params (with ':' subparams), prefix, intermediates, final
-    void Esc(in EscSequence sequence);                         // intermediates, final
-    void Osc(int command, ReadOnlySpan<char> payload);
-    void Dcs(in DcsSequence sequence, ReadOnlySpan<char> data); // buffered, capped
-    void Apc(ReadOnlySpan<char> payload);                      // Kitty graphics
-}
-```
-
-Subparameters matter: `38:2::r:g:b` and `4:3` (curly underline) use `:`. SharpMUTerm's `SgrCodes` reads them;
-MarkupString's `AnsiEscapeParser` and SharpClient's parser split on `;` only and drop them.
-
-`AnsiEscapeParser.Parse(string)` keeps its signature and becomes a one-shot decoder with the VT handlers only.
-
-#### Tag tokenizer
-
-MXP, Pueblo and HTML share SGML-ish lexing: `<NAME attr=value attr="quoted">`, `</NAME>`, `<!ELEMENT …>`,
-`&name;`, `&#n;`, `&#xh;`. One `TagTokenizer` runs over ground text while any tag protocol is active, with the
-caps above, and hands `TagToken`s to tag handlers. Which protocol is active is decoder state, switched by the
-host (`EnableProtocol("mxp")` after telnet option 91; Pueblo after its handshake) or by a handler (`ESC [ 6 z`).
-
-#### Handlers (the protocol plugins)
-
-```csharp
-public interface IDecoderPlugin
-{
-    string Name { get; }                                // "vt", "osc8", "mslp", "mxp", "pueblo", "html"
-    void Register(DecoderBuilder builder);              // adds handlers below; called once per registry
-    DecoderCapabilities Capabilities { get; }           // what it can read, for negotiation
-}
-
-public delegate bool CsiHandler(in CsiSequence seq, DecodeContext context);
-public delegate bool OscHandler(ReadOnlySpan<char> payload, DecodeContext context);
-public delegate bool TagHandler(in TagToken tag, DecodeContext context);
-public delegate bool EntityHandler(ReadOnlySpan<char> name, DecodeContext context);
-
-public sealed class DecoderBuilder
-{
-    public DecoderBuilder OnCsi(CsiIdentifier id, CsiHandler handler);   // { Prefix, Intermediates, Final }
-    public DecoderBuilder OnEsc(EscIdentifier id, EscHandler handler);
-    public DecoderBuilder OnOsc(int command, OscHandler handler);
-    public DecoderBuilder OnDcs(CsiIdentifier id, DcsHandler handler);
-    public DecoderBuilder OnApc(ApcHandler handler);
-    public DecoderBuilder OnTag(string protocol, string name, TagHandler handler);
-    public DecoderBuilder OnEntity(string protocol, EntityHandler handler);
-    public DecoderBuilder OnState<T>(Func<T> create) where T : class;    // per-connection state a plugin owns
-}
-```
-
-Dispatch follows xterm.js: handlers for one identifier are tried newest first, `true` stops, `false` falls through.
-An unclaimed sequence is dropped; an unclaimed tag is dropped on a line allowed to use it and literal otherwise
-(the MXP plugin decides which, through its line mode).
-
-`DecodeContext` is what a handler may touch:
-
-```csharp
-public sealed class DecodeContext
-{
-    public ref AnsiStyle Style { get; }                 // the SGR state
-    public T State<T>() where T : class;                // the plugin's own state (MXP line mode, element definitions)
-    public void Open(IMarkup markup);                   // push a layer over text that follows
-    public void Close(IMarkup markup);                  // pop to it (closing anything opened since, as HTML does)
-    public void Point(IPointMarkup point);              // a sound, a bell, a clear
-    public void Text(ReadOnlySpan<char> text);          // text a handler produces (an entity, a literal tag)
-    public void EndLine();
-    public void Raise(DecodeEvent e);                   // out-of-band: see below
-    public IDecodePolicy Policy { get; }                // trust and limits, see Security
-}
-```
-
-`Open`/`Close` produce `MarkupText` layers, so MXP `<COLOR>`, Pueblo `<FONT>` and SGR all end up as the same
-`AnsiMarkup` the server-side code already writes, and the render side needs no protocol knowledge.
-
-`DecodeEvent` covers what is not text: `TitleChanged` (OSC 0/2), `ReplyToServer(string)` (MXP `<SUPPORTS>`,
-`<VERSION>`, a DA/XTVERSION answer), `VariableSet(name, value)` (MXP `<VAR>`, used by gauges), `FrameOpened`,
-`FrameClosed`, `EntityDefined`, `ElementDefined`, `ProtocolChanged`, `PaletteChanged` (OSC 4/10/11),
-`ClipboardRequest` (OSC 52, denied by default). The client decides what to do with each; the decoder never
-writes to the socket.
-
-#### Shipped plugins and where they live
-
-Each protocol package gains a decoder next to its emitter, so a package speaks its protocol both ways:
-
-| Plugin | Package | Reads |
-|---|---|---|
-| `vt` | `MarkupString.Ansi` | SGR in full (including `:` subparams, 8 conceal, 21 double underline, 58/59 underline colour), C0 controls, CSI `J`/`H` as `ClearScreen` points; other CSI dropped (current behaviour) unless the screen tier is on |
-| `osc8` | `MarkupString.Ansi` | hyperlinks, with `id` |
-| `mslp` | `MarkupString.Ansi` | `OSC 68` command links (what `TerminalFeatures.CommandLinks` writes) |
-| `osc-title`, `osc-palette` | `MarkupString.Ansi` | OSC 0/1/2, 4/10/11/104 as events |
-| `kitty`, `iterm-image`, `sixel` | `MarkupString.Ansi` | pictures as `ImageMarkup` with inline data, off by default |
-| `mxp` | `MarkupString.Mxp` | line modes, open/secure tags, `!ELEMENT`, `!ENTITY`, `SEND` (with menus and `PROMPT`), `A`, `IMAGE`, `SOUND`/`MUSIC`, `FRAME`/`DEST`, `VAR`, `GAUGE`, `STAT`, `EXPIRE`, `RELOCATE`, `USER`/`PASSWORD`, room tags, `SUPPORT`/`VERSION` replies |
-| `pueblo` | `MarkupString.Pueblo` | the HTML subset, `XCH_CMD`, `xch_sound`, `xch_pane`, `xch_page clear`, `xch_mudtext` |
-| `html` | `MarkupString.Html` | raw HTML through an `HtmlTagPolicy` (the portal's `wshtml()` frames) |
-
-The MXP plugin should be a port of SharpMUTerm's `MxpParser` and its tests, not a new parser: it is the most
-complete of the four, and its edge cases are the ones listed above. The same goes for `PuebloParser`.
-
-### 2. Display model
-
-`MarkupText` is the display entity. It already has what a display needs: immutable runs with layered markup,
-grapheme-safe slicing, display-cell width, wrapping, JSON that keeps unknown layers, and the shared vocabulary
-(`ImageMarkup`, `SoundMarkup`, `PaneMarkup`, `GaugeMarkup`, `StatusMarkup`, `VariableMarkup`, `ClearScreenMarkup`,
-`ExpireLinksMarkup`, `RelocateMarkup`, `LoginPromptMarkup`, `BellMarkup`). Using it means the portal's path and the
-decoded path end in the same type, and a trigger highlight is one more layer.
-
-Gaps to close in the vocabulary, found by mapping what the client models carry onto it:
-
-| Need | Today | Proposal |
-|---|---|---|
-| MXP `<SEND>` menu (`href="a|b" hint="…|A|B"`), SharpMUTerm's `SendChoice` | `AnsiMarkup` link is one URL or command | `CommandMenuMarkup(IReadOnlyList<CommandChoice>)` in core |
-| `<SEND PROMPT>` (put in the input line, do not send) | none | `LinkKind.Prompt` |
-| OSC 8 `id` | none | `AnsiStyle.LinkId` |
-| Conceal, double/curly underline, underline colour | none | `AnsiStyle.Concealed`, `UnderlineStyle`, `UnderlineColor` |
-| MXP room parts (`ESC[10z`–`12z`, `<RName>`…) used by SharpMUTerm's mapper | none | `RoomPartMarkup(RoomPart)` as an `IDataMarkup`, so it never changes how text looks |
-| MXP custom element `FLAG` (`set hp`) | none | `ElementFlagMarkup(string)` as an `IDataMarkup` |
-| A trigger highlight, SharpMUTerm's `RuleColor` | none | `HighlightMarkup(colour, scope: Text or Line)` |
-| Image size in cells or percent (SharpMUTerm `ImageExtent`) | `ImageMarkup` has pixels | add the unit to `ImageMarkup` |
-
-A line is an envelope around one `MarkupText`:
-
-```csharp
-public sealed record DisplayLine(MarkupText Content, LineKind Kind)   // Output, Prompt, Echo, System
-{
-    public DateTimeOffset Received { get; init; }
-    public string? Destination { get; init; }      // MXP <DEST>, Pueblo xch_pane: which pane it belongs in
-    public long Sequence { get; init; }            // stable id for scrollback and @key in Blazor
-}
-```
-
-Scrollback, search, logging and triggers stay client-owned and work on `Content.ToPlainText()` and slices of it,
-as they do on `StyledLine.Text` today.
-
-### 3. Renderers
-
-`MarkupFormat` renderers write strings. Cells and component spans are not strings, so they need a second, structured
-path that walks the runs once and folds each run's layers into one resolved style.
-
-#### Resolved style and style contributors
-
-```csharp
-public readonly record struct DisplayStyle
-{
-    public DisplayColor Foreground { get; init; }     // already resolved to RGB, or Default
-    public DisplayColor Background { get; init; }
-    public TextAttributes Attributes { get; init; }   // bold, faint, italic, underline kinds, blink, inverse, conceal, strike, overline
-    public DisplayColor UnderlineColor { get; init; }
-    public int InteractionId { get; init; }           // 0 = none; index into the line's interaction table
-    public int PictureId { get; init; }               // 0 = none
-}
-
-public interface IStyleContributor                    // registered per markup type, like an emitter
-{
-    Type MarkupType { get; }
-    void Apply(IMarkup markup, ref StyleBuilder style, in ResolveContext context);
-}
-```
-
-`ResolveContext` carries the output's capabilities and an `IColorResolver`, which is where SharpMUTerm's theme
-lookup and contrast floor (`Contrast.Legible`) plug in, and where SharpClient's phosphor default lives. Today each
-client resolves colours in its own renderer.
-
-`AnsiMarkup`, `HtmlMarkup` (`b`, `i`, `u`, `font color`), the shared vocabulary and `HighlightMarkup` ship
-contributors. A layer with none contributes nothing and its text still comes out, as in the string renderers.
-
-Interactions (links, command menus, prompt links, image links) go into a per-line table so a renderer can hit-test
-without carrying strings in every cell:
-
-```csharp
-public sealed record Interaction(InteractionKind Kind, string Target, string? Hint,
-                                 IReadOnlyList<CommandChoice>? Choices, string? GroupId);
-```
-
-#### Target 1: terminal
-
-The existing `MarkupFormat.Ansi` emitter, unchanged, with `TerminalProfile`, `TerminalFeatures` and
-`WithAnsiOutput(depth)`. SharpMUTerm running inside kitty or Windows Terminal reaches the screen through
-SharpConsoleUI, so its first step is a `MarkupFormat.Custom("sharpconsoleui")` emitter (in SharpMUTerm, or a
-small `MarkupString.SharpConsoleUI` package) that replaces `MarkupFormatter`. It uses the same `IColorResolver`.
-
-#### Target 2: cell grid
-
-New. Lays a `MarkupText` out to a width with the existing wrapping (`TextLayout`, and the internal `LineWrapper`
-behind it) and `DisplayWidth`, and writes cells:
-
-```csharp
-public readonly record struct Cell(
-    string Grapheme,            // whole cluster: base plus combining marks; "" for a wide character's second column
-    DisplayStyle Style,
-    byte Width,                 // 1 or 2; 0 on the continuation
-    PictureSlice Picture);      // (PictureId, Row, Column) when the cell is part of a picture
-
-public interface ICellSurface
-{
-    int Width { get; }
-    void Write(int row, int column, in Cell cell);
-    void EndRow(int row, RowInfo info);          // soft-wrapped or hard break, for copy and reflow
-}
-
-public sealed class CellRenderer
-{
-    public CellLayout Layout(DisplayLine line, int width, in ResolveContext context);   // rows, interactions, pictures
-    public void Draw(CellLayout layout, ICellSurface surface, int firstRow);
-    public Interaction? HitTest(CellLayout layout, int row, int column);
-}
-```
-
-`Grapheme` is a string rather than SharpMUTerm's `Rune` plus `Combiners`, because a ZWJ emoji or a flag is several
-runes and must stay one cell pair. A host that wants runes splits it.
-
-Pictures reuse SharpMUTerm's approach: a picture is laid out as a block of picture cells, so it scrolls and clips
-with text. The host decides how to draw a picture cell: Skia draws the bitmap slice; a real terminal gets the
-Kitty placeholder, sixel, iTerm2 or half blocks, chosen through `TerminalFeatures` as the ANSI emitter does now.
-
-Adapters: SharpMUTerm's `CellGrid` (window), a SharpConsoleUI control that owns its cells (TUI output panes, phase 3),
-or Terminal.Gui.
-
-#### Target 3: web spans
-
-Two forms from the same walk:
-
-- `MarkupFormat.Html` as it is, for the portal, which writes one HTML string per line.
-- `SpanRenderer`, for component UIs that attach handlers (SharpClient's `@onclick`):
-
-```csharp
-public readonly record struct DisplaySpan(string Text, string? CssClass, string? InlineStyle,
-                                          Interaction? Interaction, ImageMarkup? Image, IPointMarkup? Point);
-
-public static IReadOnlyList<DisplaySpan> Spans(this DisplayLine line, in ResolveContext context);
-```
-
-Class names and CSS variables come from `AnsiCss` (`ms-*`), so SharpClient and the portal can share one stylesheet
-and theme. A `MarkupString.Blazor` package with a `<DisplayLineView>` component is optional and would remove
-`OutputView`'s per-segment markup.
-
-### Capability negotiation
-
-Capabilities flow in two directions and meet at one object per connection.
-
-```csharp
-public sealed record OutputCapabilities(
-    AnsiColorDepth Colors,
-    TextAttributes Attributes,         // what it can draw; blink and conceal are often off by choice
-    InteractionKinds Interactions,     // Url, Command, Prompt, Menu; none for a log file
-    PictureKinds Pictures,             // Bitmap, KittyPlaceholder, Sixel, InlineImage, HalfBlock, AltText
-    bool Sound, bool Panes, bool Gauges,
-    UnicodeLevel Unicode);             // Full, NoWide, Ascii (AsciiFold)
-
-public sealed record ClientCapabilities(OutputCapabilities Output, DecoderCapabilities Input, UserChoices Choices)
-{
-    public ClientCapabilities Effective { get; }       // Output ∩ Input ∩ Choices
-    public MttsFlags ToMtts();                         // for TelnetNegotiationCore's TTYPE cycle
-    public string AnswerMxpSupport(IReadOnlyList<string> asked);   // "<SUPPORTS +B +COLOR -IMAGE …>"
-    public string AnswerMxpVersion(string client, string version);
-}
-```
-
-Inbound: the client should only claim what it can both read and show. A cell grid in a terminal without picture
-support answers `-IMAGE` to MXP, so a game that checks sends text instead of a picture nobody will see. This
-generalises SharpMUTerm's `MxpParser.AnswerSupport`, which already refuses to claim a tag its handler ignores.
-`ToMtts` sets ANSI, UTF-8, 256 colours, truecolor, MSLP, screen reader and the rest from the same object.
-
-Outbound: each renderer takes `OutputCapabilities` in its `ResolveContext` and degrades on its own ladder:
-
-| Feature | Ladder |
-|---|---|
-| Colour | truecolor → xterm-256 (redmean nearest, `AnsiColor.NearestXterm`) → 16 → attributes only → none |
-| Picture | bitmap → Kitty placeholder → iTerm2 inline → sixel → half blocks → alt text |
-| Link | clickable with hover group → underlined text → text |
-| Command menu | menu → first choice as a link → text |
-| Wide or emoji text | as is → `AsciiFold` |
-| Sound, pane, gauge | native → text (pane content goes to the main view) → nothing |
-
-The ladders for colour, pictures and Unicode exist in `MarkupString.Ansi` already; this lifts them to a shared
-`OutputCapabilities` so the cell and span renderers use the same rules.
-
-### Registration
-
-Same pattern as `MarkupRegistry`: immutable, explicit, built once, AOT safe.
-
-```csharp
-var decoders = DecoderRegistry.Empty
-    .WithVt()                                // MarkupString.Ansi
-    .WithHyperlinks()
-    .WithMxp(new MxpDecoderOptions { Client = "SharpMUTerm", Version = v })   // MarkupString.Mxp
-    .WithPueblo();                           // MarkupString.Pueblo
-
-var display = DisplayRegistry.Empty
-    .WithAnsiStyles()                        // style contributors for AnsiMarkup
-    .WithSharedVocabulary()
-    .WithHtmlStyles();
-
-// per connection
-var decoder = decoders.CreateDecoder(policy: DecodePolicy.ForGame(world));
-decoder.LineReady += line => scrollback.Add(line);
-decoder.Event += e => session.Handle(e);
-decoder.Feed(chunk);
-decoder.EndPrompt();                         // on GA / EOR
-```
-
-A registry is shared; a `Decoder` holds one connection's state (style, element stack, MXP definitions, line mode)
-and is not thread-safe, like the client parsers it replaces.
-
-### Security
-
-The decoder reads text written by other players. `IDecodePolicy` holds the decisions:
-
-- Trust per source: MXP line modes decide what a line may use. A plugin asks `context.Policy` before turning
-  text into an interaction, a fetch or an event.
-- URLs pass `UrlSafety.IsSafeNavigableUrl` before they become a link or an image.
-- Fetching a picture or sound tells its host the player's address (SharpClient's settings already say so), so
-  `ImageMarkup` from a decoder is inert until the client chooses to fetch it.
-- OSC 52 (clipboard) and title changes are events the client can refuse; clipboard writes are refused by default.
-- Caps on every buffer, the element stack, entity expansion depth and the number of MXP definitions.
-- Raw HTML only through `HtmlTagPolicy`.
-
-### Screen tier (optional)
-
-MUDs mostly use SGR, but some send cursor addressing for a status area (`DECSTBM` scroll regions, `CUP`, `EL`), and
-MOO editors and door games want a real screen. All three clients drop non-SGR CSI today. A later `vt-screen` plugin
-can claim those sequences and drive a `ScreenBuffer` of `Cell`s instead of the line builder, with the line flow
-continuing below the scroll region. It stays opt-in per world, because a stray cursor move from a game that
-assumes 80×24 is worse in a reflowing pane than dropping it.
-
-## Conversions and work plan
-
-What each source becomes on each target, including pictures (Kitty, sixel, iTerm2, MXP), and the order of work, are in
-`docs/superpowers/plans/2026-11-06-display-pipeline.md`.
-
-## Testing
-
-- Round trip: for every format with an emitter, `Decode(Render(x, f)) ≈ x` as a property over generated
-  `MarkupText` (an extension of `RoundTripProperties`). This tests the decoder and the emitters against each other.
-- Port the client suites: SharpMUTerm's `AnsiParser`, `MxpParser` and `PuebloParser` tests and SharpClient's
-  parser tests become decoder tests, so nothing they pin is lost.
-- Chunking: every test case fed whole and split at every index gives the same lines.
-- Fuzzing: random bytes never throw, never exceed caps, and never leave state that swallows the next line.
-- Captured transcripts from PennMUSH, TinyMUX, an MXP game and a Pueblo game, checked as approved snapshots of cells
-  and spans.
-- Renderer parity: the same `DisplayLine` drawn as cells and as spans gives the same text, styles and interaction
-  ranges, in the spirit of SharpMUTerm's cell-for-cell comparison of its two front ends.
-
-## Migration
-
-| Phase | MarkupString | SharpMUTerm | SharpClient | Portal |
-|---|---|---|---|---|
-| 1 | Tokenizer, `vt`, `osc8`, `mslp` decoders; `DisplayLine`; vocabulary gaps; `AnsiEscapeParser` on the new tokenizer | `ILineParser` adapter over the decoder that still yields `StyledLine`, behind a setting | — | Plain-text frames decoded instead of ANSI-stripped |
-| 2 | `mxp`, `pueblo` decoders (ported), `ClientCapabilities` | Switch to the adapter; delete the three parsers | Replace `AnsiParser`/`MxpParserState` with the decoder | — |
-| 3 | `DisplayStyle`, contributors, `SpanRenderer`, `CellRenderer` | `sharpconsoleui` emitter replaces `MarkupFormatter`; window output panes on `CellRenderer` | `OutputView` on `SpanRenderer` | Optionally the same `SpanRenderer` |
-| 4 | `vt-screen` | Opt-in per world | — | — |
-
-Phase 1 changes nothing a client sees and can ship on its own.
-
-## Package shape
-
-| Package | Adds |
-|---|---|
-| `MarkupString` | Decoder abstractions, `VtTokenizer`, `TagTokenizer`, `DisplayLine`, `DisplayStyle`, `IStyleContributor`, `OutputCapabilities`, `CellRenderer`, `SpanRenderer`, new vocabulary records |
-| `MarkupString.Ansi` | `vt`, `osc8`, `mslp`, title, palette, picture decoders; `AnsiMarkup` style contributor |
-| `MarkupString.Mxp` | `mxp` decoder, `<SUPPORTS>`/`<VERSION>` answers |
-| `MarkupString.Pueblo` | `pueblo` decoder |
-| `MarkupString.Html` | `html` decoder through `HtmlTagPolicy`; `HtmlMarkup` style contributor |
-| `MarkupString.Blazor` (optional) | `<DisplayLineView>` |
-
-The alternative is one new `MarkupString.Display` package holding the decoders and renderers. It keeps the
-existing packages untouched, but splits each protocol across two packages and makes `WithMxp()` mean only half of
-MXP. The table above is the recommendation.
-
-## Open questions
-
-1. Is the screen tier in scope for the first version, or only lines?
-2. Should the SharpConsoleUI emitter live in SharpMUTerm or in a MarkupString package?
-3. Is porting SharpMUTerm's MXP and Pueblo parsers into MarkupString acceptable, given SharpMUTerm is MIT and
-   MarkupString is Apache-2.0? Both are permissive and have the same owners, but the notice has to come along.
-4. Should `CellRenderer` and `SpanRenderer` sit in core, or does core stay free of any renderer and take them in
-   a new package?

From 4f88c701c8de8cc8c89b2ed263cef38c1985e4c6 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 22:09:02 +0000
Subject: [PATCH 13/19] Point the package READMEs at decoding

---
 MarkupString.Ansi/README.md   | 7 +++++++
 MarkupString.Mxp/README.md    | 6 ++++++
 MarkupString.Pueblo/README.md | 5 +++++
 3 files changed, 18 insertions(+)

diff --git a/MarkupString.Ansi/README.md b/MarkupString.Ansi/README.md
index 2d22523..dd1a19d 100644
--- a/MarkupString.Ansi/README.md
+++ b/MarkupString.Ansi/README.md
@@ -138,6 +138,13 @@ confirmed: several terminals read Kitty graphics without the Unicode placeholder
 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](https://github.com/SharpMUSH/MarkupString/blob/main/docs/decoding.md) and [Display](https://github.com/SharpMUSH/MarkupString/blob/main/docs/display.md).
+
 ## Styling the HTML output
 
 The HTML-family emitters write `ms-*` classes for the attributes with a fixed rendering (bold,
diff --git a/MarkupString.Mxp/README.md b/MarkupString.Mxp/README.md
index 88d0f6c..4f0b046 100644
--- a/MarkupString.Mxp/README.md
+++ b/MarkupString.Mxp/README.md
@@ -33,6 +33,12 @@ line.Render(MarkupFormat.Mxp, registry);
 These are MXP's secure elements, which a client acts on only on a line opened in secure mode, so render
 through a registry with `WithMxpSecureLines()`.
 
+## Reading MXP
+
+`WithMxp()` on a `DecoderRegistry` reads MXP from a server: line modes, open and secure tags, `SEND`
+menus, custom elements and entities. Turn it on with `decoder.EnableProtocol(MxpDecoding.Protocol)`
+once telnet negotiates it. See [Decoding](https://github.com/SharpMUSH/MarkupString/blob/main/docs/decoding.md#mxp).
+
 ## What the client supports
 
 MXP lets a server ask which elements a client renders (`<SUPPORT>`), and a client that answered
diff --git a/MarkupString.Pueblo/README.md b/MarkupString.Pueblo/README.md
index 3f6dfab..5430e10 100644
--- a/MarkupString.Pueblo/README.md
+++ b/MarkupString.Pueblo/README.md
@@ -30,6 +30,11 @@ line.Render(MarkupFormat.Pueblo, registry);
 // <img xch_sound="play" href="door.wav" xch_volume="80"><xch_pane action="redirect" name="map" panetitle="The Map">North: the gate<xch_pane action="redirect" name="_previous">
 ```
 
+## Reading Pueblo
+
+`WithPueblo()` on a `DecoderRegistry` reads Pueblo's HTML from a server. Turn it on with
+`decoder.EnableProtocol(PuebloDecoding.Protocol)` after the greeting. See [Decoding](https://github.com/SharpMUSH/MarkupString/blob/main/docs/decoding.md#pueblo).
+
 ## Line endings
 
 A Pueblo connection is in HTML mode, where a newline is whitespace, so `MarkupFormat.Pueblo` writes a

From 3d655b822d60849d8436ef2fbed9649716b7133c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 22:10:55 +0000
Subject: [PATCH 14/19] Smoke-test decoding under native AOT

---
 MarkupString.AotSmoke/Program.cs | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/MarkupString.AotSmoke/Program.cs b/MarkupString.AotSmoke/Program.cs
index a93414e..736e4d4 100644
--- a/MarkupString.AotSmoke/Program.cs
+++ b/MarkupString.AotSmoke/Program.cs
@@ -1,10 +1,15 @@
 using System.Buffers;
 using MarkupString;
 using MarkupString.Ansi;
+using MarkupString.Ansi.Decoding;
+using MarkupString.Decoding;
+using MarkupString.Display;
 using MarkupString.Html;
 using MarkupString.Layout;
 using MarkupString.Mxp;
+using MarkupString.Mxp.Decoding;
 using MarkupString.Pueblo;
+using MarkupString.Pueblo.Decoding;
 
 // Native-AOT smoke test. It is published with PublishAot and run in CI: the publish must produce no
 // IL2xxx/IL3xxx warning, and the binary must exit 0. What it exercises is the whole pipeline that a
@@ -129,6 +134,21 @@
 	|| Graphemes.SnapEnd(longCluster, 1000) != longCluster.Length)
 	failures.Add("long cluster snapping failed");
 
+// Decoding: terminal text, a sixel picture and MXP, rendered for a page and for a cell grid.
+var decoders = DecoderRegistry.Empty.WithVt().WithPictures().WithMxp().WithPueblo();
+var decoder = decoders.CreateDecoder();
+decoder.EnableProtocol(MxpDecoding.Protocol);
+var decoded = new List<DisplayLine>(decoder.Feed(
+	"\e[1;31mred\e[0m \e]8;;https://example.com\e\\link\e]8;;\e\\\n\e[1z<SEND look>look</SEND>\n\eP0;1q#1;2;100;0;0#1~~\e\\\n"));
+var spans = SpanRenderer.Render(decoded[0].Content, AnsiDisplay.Default, new DisplayOptions());
+if (spans[0].Style.Foreground != new RgbColor(170, 0, 0) || spans[^1].Style.Interaction?.Kind != InteractionKind.Url)
+	failures.Add("decoding ANSI failed");
+if (SpanRenderer.Render(decoded[1].Content, AnsiDisplay.Default, new DisplayOptions())[0].Style.Interaction?.Target != "look")
+	failures.Add("decoding MXP failed");
+if (decoder.Pictures().Count != 1
+	|| CellRenderer.Layout(decoded[2].Content, 80, AnsiDisplay.Default, new DisplayOptions()).Rows[0].Cells[0].Style.Picture is null)
+	failures.Add("decoding a sixel picture failed");
+
 if (failures.Count > 0)
 {
 	Console.Error.WriteLine("AOT smoke test failed:");

From 76a4cdbb803fd7f2a197f2d0145e8db7efe7251a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 23:02:42 +0000
Subject: [PATCH 15/19] Decode Kitty animation frames, keep the OSC 8 id as a
 link group, reduce colours to 16 or 256

Kitty a=f adds or edits frames (base c, edit r, offset x/y, blend unless X=1,
background Y, gap z) and a=a sets a frame's gap; a moving StoredPicture is
given as a looping GIF. Re-sending a picture starts it over as one frame.

OSC 8 id= becomes a LinkGroupMarkup pen, which Resolve turns into
Interaction.Group.

Degrade picks the nearest palette colour by redmean distance at Standard and
Xterm256, through the IColorResolver when there is one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rqqt7WGskvSsoRXvKMqybx
---
 CHANGELOG.md                                  |   5 +-
 MarkupString.Ansi/Decoding/PictureStore.cs    |  67 +++--
 MarkupString.Ansi/Decoding/PicturesPlugin.cs  | 236 +++++++++++++++++-
 MarkupString.Ansi/Decoding/VtPlugins.cs       |  24 +-
 MarkupString.Ansi/PublicAPI.Unshipped.txt     |   6 +-
 MarkupString.Tests/Decoding/DisplayTests.cs   |  27 ++
 .../Decoding/PictureDecodingTests.cs          |  55 ++++
 .../Decoding/VtDecodingTests.cs               |  12 +
 MarkupString/Display/DisplayRegistry.cs       |  67 ++++-
 MarkupString/Elements/CommandMenuMarkup.cs    |   7 +
 MarkupString/Elements/ElementCodecs.cs        |   3 +
 MarkupString/PublicAPI.Unshipped.txt          |  12 +
 docs/decoding.md                              |  13 +-
 docs/display.md                               |   8 +-
 14 files changed, 503 insertions(+), 39 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 75f1364..10765f9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -31,7 +31,10 @@ follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   grid (wide characters, tabs, wrapping, picture cells, hit testing). `DisplayRegistry.Core.WithAnsi()` folds
   terminal styles; `TerminalProfile.ToOutputCapabilities` and `ToTerminalFeatures` convert between the two
   models. See [Display](docs/display.md).
-- `CommandMenuMarkup` (a menu of commands, or a prompt) and `HighlightMarkup` (a background) in core, with codecs.
+- `CommandMenuMarkup` (a menu of commands, or a prompt), `HighlightMarkup` (a background) and `LinkGroupMarkup`
+  (an OSC 8 `id`, which becomes `Interaction.Group`) in core, with codecs.
+- Kitty animation frames (`a=f`, and frame times with `a=a`) decode into a moving `StoredPicture`, given as a GIF.
+- Spans and cells at `ColorLevel.Standard` or `Xterm256` get the nearest colour of that palette.
 - `AnsiStyle.Concealed` (SGR 8), written as SGR 8 and as `ms-conceal` in HTML.
 - `PictureRow.FirstColumn`, for a picture row shown from a column other than its first.
 
diff --git a/MarkupString.Ansi/Decoding/PictureStore.cs b/MarkupString.Ansi/Decoding/PictureStore.cs
index fe27878..9937486 100644
--- a/MarkupString.Ansi/Decoding/PictureStore.cs
+++ b/MarkupString.Ansi/Decoding/PictureStore.cs
@@ -8,16 +8,18 @@ namespace MarkupString.Ansi.Decoding;
 /// </summary>
 public sealed class StoredPicture
 {
+	private readonly ReadOnlyMemory<byte> _file;
+	private readonly string? _fileType;
 	private ReadOnlyMemory<byte> _encoded;
 
-	internal StoredPicture(string key, int width, int height, TerminalPicture? pixels, ReadOnlyMemory<byte> encoded, string? mediaType)
+	internal StoredPicture(string key, int width, int height, TerminalPicture? pixels, ReadOnlyMemory<byte> file, string? fileType)
 	{
 		Key = key;
 		Width = width;
 		Height = height;
 		Pixels = pixels;
-		_encoded = encoded;
-		MediaType = encoded.IsEmpty ? null : mediaType;
+		_file = file;
+		_fileType = file.IsEmpty ? null : fileType;
 	}
 
 	/// <summary>What identifies it: a hash of its contents, so the same picture sent twice is stored once.</summary>
@@ -29,30 +31,54 @@ internal StoredPicture(string key, int width, int height, TerminalPicture? pixel
 	/// <summary>Its height in pixels.</summary>
 	public int Height { get; }
 
-	/// <summary>Its pixels, or null for a file this package cannot decode (a JPEG, a GIF), which only a browser can show.</summary>
-	public TerminalPicture? Pixels { get; }
-
-	/// <summary>The file's media type, such as <c>image/png</c>, or null when the server sent bare pixels.</summary>
-	public string? MediaType { get; }
-
 	/// <summary>What an <see cref="ImageMarkup.Source"/> that shows it says: <c>picture:</c> and the key.</summary>
 	public string Source => PictureStore.Scheme + Key;
 
-	/// <summary>How many bytes it holds.</summary>
-	public long Size => _encoded.Length + (Pixels?.Rgba.Length ?? 0);
+	/// <summary>
+	/// Its pixels, or null for a file this package cannot decode (a JPEG, a GIF), which only a browser can show. A
+	/// moving picture's frames are in <see cref="TerminalPicture.Frames"/>; they can grow after the picture is first
+	/// stored, as the server sends them.
+	/// </summary>
+	public TerminalPicture? Pixels { get; private set; }
+
+	/// <summary>Whether it moves: it has more than one frame.</summary>
+	public bool IsMoving => Pixels is { Frames.Count: > 1 };
+
+	/// <summary>
+	/// The type of <see cref="Encoded"/>: the file's own, such as <c>image/png</c>; <c>image/gif</c> for a moving
+	/// picture sent as frames; <c>image/png</c> for still pixels.
+	/// </summary>
+	public string MediaType => IsMoving ? "image/gif" : _fileType ?? "image/png";
 
-	/// <summary>The file as the server sent it, or, for bare pixels, the pixels as a PNG.</summary>
+	/// <summary>What the server sent, as a file: its own for a file, a looping GIF for frames, a PNG for still pixels.</summary>
 	public ReadOnlyMemory<byte> Encoded
 	{
 		get
 		{
-			if (_encoded.IsEmpty && Pixels is { } pixels) _encoded = PngWriter.Encode(pixels.Rgba.Span, pixels.Width, pixels.Height);
-			return _encoded;
+			if (!_encoded.IsEmpty) return _encoded;
+			if (IsMoving) return _encoded = GifWriter.Encode(Pixels!.Frames, Width, Height);
+			if (!_file.IsEmpty) return _file;
+			return _encoded = Pixels is { } pixels ? PngWriter.Encode(pixels.Rgba.Span, pixels.Width, pixels.Height) : default;
 		}
 	}
 
+	/// <summary>What the server sent as the file, or empty when it sent bare pixels.</summary>
+	public ReadOnlyMemory<byte> File => _file;
+
+	/// <summary>How many bytes it holds.</summary>
+	public long Size => _file.Length + PixelBytes(Pixels);
+
 	/// <summary>The picture as a <c>data:</c> address, for an <c>&lt;img&gt;</c>.</summary>
-	public string ToDataUrl() => $"data:{MediaType ?? "image/png"};base64,{Convert.ToBase64String(Encoded.Span)}";
+	public string ToDataUrl() => $"data:{MediaType};base64,{Convert.ToBase64String(Encoded.Span)}";
+
+	internal void ReplacePixels(TerminalPicture pixels)
+	{
+		Pixels = pixels;
+		_encoded = default;
+	}
+
+	internal static long PixelBytes(TerminalPicture? pixels) =>
+		pixels is null ? 0 : pixels.Frames.Count > 0 ? pixels.Frames.Sum(frame => (long)frame.Rgba.Length) : pixels.Rgba.Length;
 }
 
 /// <summary>
@@ -111,6 +137,17 @@ public StoredPicture Add(int width, int height, byte[]? rgba, ReadOnlyMemory<byt
 		return picture;
 	}
 
+	/// <summary>Replaces a held picture's pixels, as when a moving picture gains a frame.</summary>
+	internal void ReplacePixels(StoredPicture picture, TerminalPicture pixels)
+	{
+		var held = _pictures.ContainsKey(picture.Key);
+		if (held) Used -= picture.Size;
+		picture.ReplacePixels(pixels);
+		if (!held) return;
+		Used += picture.Size;
+		while (Used > Budget && _order.Count > 1 && _order.Last!.Value != picture) Remove(_order.Last.Value.Key);
+	}
+
 	/// <summary>The picture with <paramref name="key"/>, if it is still held.</summary>
 	public bool TryGet(string key, [NotNullWhen(true)] out StoredPicture? picture)
 	{
diff --git a/MarkupString.Ansi/Decoding/PicturesPlugin.cs b/MarkupString.Ansi/Decoding/PicturesPlugin.cs
index aeb6404..db530c9 100644
--- a/MarkupString.Ansi/Decoding/PicturesPlugin.cs
+++ b/MarkupString.Ansi/Decoding/PicturesPlugin.cs
@@ -118,10 +118,14 @@ private static void Complete(KittyKeys keys, string base64, DecodeContext contex
 				}
 
 				return;
-			case 't' or 'T' or 'q':
+			case 't' or 'T' or 'q' or 'f':
 				break;
+			case 'a':
+				Animate(keys, state);
+				return;
 			default:
-				// Animation (a=f, a=a, a=c): a moving picture is read as its first frame.
+				// Composing frames (a=c) is not read.
+				context.Diagnostics.UnhandledSequences++;
 				return;
 		}
 
@@ -134,6 +138,19 @@ private static void Complete(KittyKeys keys, string base64, DecodeContext contex
 
 		var bytes = FromBase64(base64);
 		if (bytes is not null && keys.Compression == 'z') bytes = Inflate(bytes, state.Store.MaxPixels * 4 + 1024);
+		if (keys.Action == 'f')
+		{
+			if (bytes is null || DecodePixels(keys, bytes, state.Store.MaxPixels) is not { } frame || !AddFrame(keys, frame, state))
+			{
+				context.Diagnostics.PicturesFailed++;
+				KittyReply(context, keys, "ENOENT:no such image, or a frame that could not be read");
+				return;
+			}
+
+			KittyReply(context, keys, null);
+			return;
+		}
+
 		var picture = bytes is null ? null : DecodeKitty(keys, bytes, state.Store);
 		if (picture is null)
 		{
@@ -151,23 +168,38 @@ private static void Complete(KittyKeys keys, string base64, DecodeContext contex
 		var (cellColumns, cellRows) = Cells(picture.Width, picture.Height, keys.Columns, keys.Rows, context.Identity);
 		var id = keys.Id;
 		if (id == 0 && keys.Number != 0) id = state.NextKittyId++;
-		if (id != 0) state.KittyImages[id] = new KittyImage(picture.Key, cellColumns, cellRows);
+		if (id != 0)
+		{
+			state.KittyImages[id] = new KittyImage(picture.Key, cellColumns, cellRows);
+			state.Animations.Remove(id);
+		}
 
 		if (keys.Action == 'T' && !keys.Virtual) Place(context, picture, cellColumns, cellRows, cursorRight: true, keys.StayPut);
 		KittyReply(context, keys with { Id = id }, null);
 	}
 
 	private static StoredPicture? DecodeKitty(KittyKeys keys, byte[] bytes, PictureStore store)
+	{
+		if (DecodePixels(keys, bytes, store.MaxPixels) is not { } pixels) return null;
+		var picture = keys.Format == 100
+			? store.Add(pixels.Width, pixels.Height, pixels.Rgba, bytes, "image/png")
+			: store.Add(pixels.Width, pixels.Height, pixels.Rgba);
+
+		// The same picture sent again starts over as one frame; its frames follow again if it moves.
+		if (picture.IsMoving) store.ReplacePixels(picture, new TerminalPicture(picture.Key, pixels.Width, pixels.Height, pixels.Rgba));
+		return picture;
+	}
+
+	/// <summary>The pixels a Kitty transmission carries: a PNG, or raw RGB or RGBA <c>s</c> × <c>v</c>.</summary>
+	private static (int Width, int Height, byte[] Rgba)? DecodePixels(KittyKeys keys, byte[] bytes, long maxPixels)
 	{
 		switch (keys.Format)
 		{
 			case 100:
-				return PngDecoder.TryDecode(bytes, store.MaxPixels, out var width, out var height, out var rgba)
-					? store.Add(width, height, rgba, bytes, "image/png")
-					: null;
+				return PngDecoder.TryDecode(bytes, maxPixels, out var width, out var height, out var rgba) ? (width, height, rgba) : null;
 			case 24 or 32:
 				{
-					if (keys.Width <= 0 || keys.Height <= 0 || (long)keys.Width * keys.Height > store.MaxPixels) return null;
+					if (keys.Width <= 0 || keys.Height <= 0 || (long)keys.Width * keys.Height > maxPixels) return null;
 					var channels = keys.Format / 8;
 					if (bytes.Length < (long)keys.Width * keys.Height * channels) return null;
 					var pixels = new byte[keys.Width * keys.Height * 4];
@@ -179,25 +211,181 @@ private static void Complete(KittyKeys keys, string base64, DecodeContext contex
 						pixels[i * 4 + 3] = channels == 4 ? bytes[i * 4 + 3] : (byte)255;
 					}
 
-					return store.Add(keys.Width, keys.Height, pixels);
+					return (keys.Width, keys.Height, pixels);
 				}
 			default:
 				return null;
 		}
 	}
 
+	// ── Kitty animation ─────────────────────────────────────────────────────────
+
+	/// <summary>The default gap between frames, as Kitty has it.</summary>
+	private const int DefaultGap = 40;
+
+	/// <summary>The most frames a moving picture is read with; later ones are dropped.</summary>
+	public const int MaxFrames = 1000;
+
+	/// <summary>
+	/// <c>a=f</c>: a frame, made on a copy of frame <c>c</c> (or blank, filled with <c>Y</c>) or written over frame
+	/// <c>r</c>, with the data put at <c>x</c>, <c>y</c>, blended over what is there unless <c>X=1</c>.
+	/// </summary>
+	private static bool AddFrame(KittyKeys keys, (int Width, int Height, byte[] Rgba) data, PictureState state)
+	{
+		if (!state.KittyImages.TryGetValue(keys.Id, out var known) || !state.Store.TryGet(known.Key, out var stored)
+			|| stored.Pixels is not { } pixels)
+		{
+			return false;
+		}
+
+		var animation = Animation(keys.Id, stored, pixels, state);
+		var size = stored.Width * stored.Height * 4;
+
+		// For a frame, c and r are frame numbers (from 1), not cells.
+		var edit = keys.Rows;
+		var baseFrame = keys.Columns;
+		byte[] canvas;
+		if (edit > 0 && edit <= animation.Frames.Count)
+		{
+			canvas = (byte[])animation.Frames[edit - 1].Clone();
+		}
+		else if (baseFrame > 0 && baseFrame <= animation.Frames.Count)
+		{
+			canvas = (byte[])animation.Frames[baseFrame - 1].Clone();
+		}
+		else
+		{
+			canvas = new byte[size];
+			if (keys.Background != 0)
+			{
+				var fill = keys.Background;
+				for (var i = 0; i < canvas.Length; i += 4)
+				{
+					canvas[i] = (byte)(fill >> 24);
+					canvas[i + 1] = (byte)(fill >> 16);
+					canvas[i + 2] = (byte)(fill >> 8);
+					canvas[i + 3] = (byte)fill;
+				}
+			}
+		}
+
+		Composite(canvas, stored.Width, stored.Height, data, keys.X, keys.Y, keys.Replace);
+
+		if (edit > 0 && edit <= animation.Frames.Count)
+		{
+			animation.Frames[edit - 1] = canvas;
+			if (keys.Gap != 0) animation.Gaps[edit - 1] = keys.Gap;
+		}
+		else
+		{
+			if (animation.Frames.Count >= MaxFrames) return true;
+			animation.Frames.Add(canvas);
+			animation.Gaps.Add(keys.Gap != 0 ? keys.Gap : DefaultGap);
+		}
+
+		Publish(stored, animation, state.Store);
+		return true;
+	}
+
+	/// <summary><c>a=a</c>: a frame's gap (<c>r</c>, <c>z</c>). Playing, stopping and looping are the client's.</summary>
+	private static void Animate(KittyKeys keys, PictureState state)
+	{
+		if (!state.KittyImages.TryGetValue(keys.Id, out var known) || !state.Store.TryGet(known.Key, out var stored)
+			|| stored.Pixels is not { } pixels)
+		{
+			return;
+		}
+
+		var frame = keys.Rows;
+		if (frame <= 0 || keys.Gap == 0) return;
+		var animation = Animation(keys.Id, stored, pixels, state);
+		if (frame > animation.Frames.Count) return;
+		animation.Gaps[frame - 1] = keys.Gap;
+		Publish(stored, animation, state.Store);
+	}
+
+	private static KittyAnimation Animation(uint id, StoredPicture stored, TerminalPicture pixels, PictureState state)
+	{
+		if (state.Animations.TryGetValue(id, out var animation)) return animation;
+		animation = new KittyAnimation();
+		if (pixels.Frames.Count > 0)
+		{
+			foreach (var frame in pixels.Frames)
+			{
+				animation.Frames.Add(frame.Rgba.ToArray());
+				animation.Gaps.Add((int)frame.Duration.TotalMilliseconds);
+			}
+		}
+		else
+		{
+			animation.Frames.Add(pixels.Rgba.ToArray());
+			animation.Gaps.Add(DefaultGap);
+		}
+
+		state.Animations[id] = animation;
+		return animation;
+	}
+
+	private static void Publish(StoredPicture stored, KittyAnimation animation, PictureStore store)
+	{
+		// A negative gap is a frame Kitty skips; it is left out.
+		var frames = new List<TerminalPictureFrame>(animation.Frames.Count);
+		for (var i = 0; i < animation.Frames.Count; i++)
+		{
+			if (animation.Gaps[i] < 0 && i > 0) continue;
+			frames.Add(new TerminalPictureFrame(animation.Frames[i], TimeSpan.FromMilliseconds(Math.Max(0, animation.Gaps[i]))));
+		}
+
+		store.ReplacePixels(stored, new TerminalPicture(stored.Key, stored.Width, stored.Height, frames));
+	}
+
+	private static void Composite(byte[] canvas, int width, int height, (int Width, int Height, byte[] Rgba) data, int left, int top, bool replace)
+	{
+		for (var y = 0; y < data.Height; y++)
+		{
+			var cy = top + y;
+			if (cy < 0 || cy >= height) continue;
+			for (var x = 0; x < data.Width; x++)
+			{
+				var cx = left + x;
+				if (cx < 0 || cx >= width) continue;
+				var s = (y * data.Width + x) * 4;
+				var d = (cy * width + cx) * 4;
+				var alpha = data.Rgba[s + 3];
+				if (replace || alpha == 255)
+				{
+					Array.Copy(data.Rgba, s, canvas, d, 4);
+					continue;
+				}
+
+				if (alpha == 0) continue;
+
+				// Source over destination, straight alpha.
+				var a = alpha / 255.0;
+				var da = canvas[d + 3] / 255.0;
+				var oa = a + da * (1 - a);
+				for (var c = 0; c < 3; c++)
+				{
+					var value = (data.Rgba[s + c] * a + canvas[d + c] * da * (1 - a)) / oa;
+					canvas[d + c] = (byte)Math.Round(value);
+				}
+
+				canvas[d + 3] = (byte)Math.Round(oa * 255);
+			}
+		}
+	}
+
 	private static void Delete(KittyKeys keys, PictureState state)
 	{
 		switch (keys.Delete)
 		{
 			case 'a' or 'A' or '\0':
 				state.KittyImages.Clear();
+				state.Animations.Clear();
 				break;
-			case 'i' or 'I':
-				state.KittyImages.Remove(keys.Id);
-				break;
-			case 'n' or 'N':
+			case 'i' or 'I' or 'n' or 'N':
 				state.KittyImages.Remove(keys.Id);
+				state.Animations.Remove(keys.Id);
 				break;
 		}
 	}
@@ -575,6 +763,13 @@ private static void DrawOverlays(DecodeContext context)
 
 	internal readonly record struct KittyImage(string Key, int Columns, int Rows);
 
+	internal sealed class KittyAnimation
+	{
+		public List<byte[]> Frames { get; } = [];
+
+		public List<int> Gaps { get; } = [];
+	}
+
 	internal sealed class Overlay(ImageMarkup image, int rows, int columns, int column)
 	{
 		public ImageMarkup Image { get; } = image;
@@ -620,6 +815,16 @@ internal readonly record struct KittyKeys
 
 		public bool StayPut { get; init; }
 
+		public int X { get; init; }
+
+		public int Y { get; init; }
+
+		public bool Replace { get; init; }
+
+		public uint Background { get; init; }
+
+		public int Gap { get; init; }
+
 		public static KittyKeys Parse(ReadOnlySpan<char> control)
 		{
 			var keys = new KittyKeys { Action = 't', Medium = 'd', Format = 32 };
@@ -646,6 +851,11 @@ public static KittyKeys Parse(ReadOnlySpan<char> control)
 					'm' => keys with { More = number == 1 },
 					'U' => keys with { Virtual = number == 1 },
 					'C' => keys with { StayPut = number == 1 },
+					'x' => keys with { X = number },
+					'y' => keys with { Y = number },
+					'X' => keys with { Replace = number == 1 },
+					'Y' => keys with { Background = uint.TryParse(value, NumberStyles.None, CultureInfo.InvariantCulture, out var fill) ? fill : 0 },
+					'z' => keys with { Gap = number },
 					_ => keys,
 				};
 			}
@@ -723,6 +933,8 @@ internal sealed class PictureState
 
 	public Dictionary<uint, PicturesPlugin.KittyImage> KittyImages { get; } = [];
 
+	public Dictionary<uint, PicturesPlugin.KittyAnimation> Animations { get; } = [];
+
 	public uint NextKittyId { get; set; } = 0x7F000000;
 
 	public StringBuilder? Chunks { get; set; }
diff --git a/MarkupString.Ansi/Decoding/VtPlugins.cs b/MarkupString.Ansi/Decoding/VtPlugins.cs
index 02ccd8c..6b7600f 100644
--- a/MarkupString.Ansi/Decoding/VtPlugins.cs
+++ b/MarkupString.Ansi/Decoding/VtPlugins.cs
@@ -34,6 +34,9 @@ public static class VtPens
 
 	/// <summary>The OSC 8 or MSLP link, an <see cref="AnsiMarkup"/> with only a link.</summary>
 	public const string Link = "link";
+
+	/// <summary>The OSC 8 link's <c>id</c>, a <see cref="LinkGroupMarkup"/>, set and cleared with <see cref="Link"/>.</summary>
+	public const string LinkGroup = "link-group";
 }
 
 /// <summary>SGR (<c>CSI … m</c>): colours and attributes, colon subparameters included.</summary>
@@ -350,6 +353,18 @@ public sealed class OscPlugin : IDecoderPlugin
 	/// <summary>The longest OSC 8 address taken, as kitty and VTE cap it.</summary>
 	public const int MaxUriLength = 2083;
 
+	/// <summary>The <c>id</c> among OSC 8's params (<c>key=value</c> pairs split by <c>:</c>), or null.</summary>
+	private static string? LinkId(ReadOnlySpan<char> parameters)
+	{
+		foreach (var range in parameters.Split(':'))
+		{
+			var pair = parameters[range];
+			if (pair.StartsWith("id=", StringComparison.Ordinal) && pair.Length > 3 && pair.Length <= 256) return pair[3..].ToString();
+		}
+
+		return null;
+	}
+
 	/// <summary>The one instance.</summary>
 	public static OscPlugin Instance { get; } = new();
 
@@ -374,13 +389,15 @@ public void Register(DecoderBuilder builder)
 				if (uri.IsEmpty || uri.Length > MaxUriLength)
 				{
 					context.SetPen(VtPens.Link, null);
+					context.SetPen(VtPens.LinkGroup, null);
 					return true;
 				}
 
 				var target = uri.ToString();
-				context.SetPen(VtPens.Link, UrlSafety.IsSafeNavigableUrl(target)
-					? new AnsiMarkup(new AnsiStyle { LinkUrl = target, LinkKind = LinkKind.Url })
-					: null);
+				var safe = UrlSafety.IsSafeNavigableUrl(target);
+				context.SetPen(VtPens.Link, safe ? new AnsiMarkup(new AnsiStyle { LinkUrl = target, LinkKind = LinkKind.Url }) : null);
+				var id = safe ? LinkId(payload[..separator]) : null;
+				context.SetPen(VtPens.LinkGroup, id is null ? null : new LinkGroupMarkup(id));
 				return true;
 			})
 			.OnOsc(68, static (payload, context) =>
@@ -390,6 +407,7 @@ public void Register(DecoderBuilder builder)
 				if (parts is not ["1", var type, var command] || command.Length == 0) return false;
 				if (!type.Equals("SEND", StringComparison.OrdinalIgnoreCase)) return false;
 				context.SetPen(VtPens.Link, new AnsiMarkup(new AnsiStyle { LinkUrl = command, LinkKind = LinkKind.Command }));
+				context.SetPen(VtPens.LinkGroup, null);
 				context.State<VtState>().MslpUnderlined = false;
 				return true;
 			})
diff --git a/MarkupString.Ansi/PublicAPI.Unshipped.txt b/MarkupString.Ansi/PublicAPI.Unshipped.txt
index e0db246..090122a 100644
--- a/MarkupString.Ansi/PublicAPI.Unshipped.txt
+++ b/MarkupString.Ansi/PublicAPI.Unshipped.txt
@@ -76,7 +76,6 @@ MarkupString.Ansi.Decoding.StoredPicture
 MarkupString.Ansi.Decoding.StoredPicture.Encoded.get -> System.ReadOnlyMemory<byte>
 MarkupString.Ansi.Decoding.StoredPicture.Height.get -> int
 MarkupString.Ansi.Decoding.StoredPicture.Key.get -> string!
-MarkupString.Ansi.Decoding.StoredPicture.MediaType.get -> string?
 MarkupString.Ansi.Decoding.StoredPicture.Pixels.get -> MarkupString.Ansi.TerminalPicture?
 MarkupString.Ansi.Decoding.StoredPicture.Size.get -> long
 MarkupString.Ansi.Decoding.StoredPicture.Source.get -> string!
@@ -88,3 +87,8 @@ static MarkupString.Ansi.Decoding.PictureDecoding.Pictures(this MarkupString.Dec
 static MarkupString.Ansi.Decoding.PictureDecoding.WithPictures(this MarkupString.Decoding.DecoderRegistry! registry) -> MarkupString.Decoding.DecoderRegistry!
 static MarkupString.Ansi.Decoding.PicturesPlugin.Instance.get -> MarkupString.Ansi.Decoding.PicturesPlugin!
 static MarkupString.Ansi.Decoding.PicturesPlugin.Pictures(MarkupString.Decoding.Decoder! decoder) -> MarkupString.Ansi.Decoding.PictureStore!
+MarkupString.Ansi.Decoding.StoredPicture.File.get -> System.ReadOnlyMemory<byte>
+MarkupString.Ansi.Decoding.StoredPicture.IsMoving.get -> bool
+MarkupString.Ansi.Decoding.StoredPicture.MediaType.get -> string!
+const MarkupString.Ansi.Decoding.PicturesPlugin.MaxFrames = 1000 -> int
+const MarkupString.Ansi.Decoding.VtPens.LinkGroup = "link-group" -> string!
diff --git a/MarkupString.Tests/Decoding/DisplayTests.cs b/MarkupString.Tests/Decoding/DisplayTests.cs
index 8b1082f..e73d0de 100644
--- a/MarkupString.Tests/Decoding/DisplayTests.cs
+++ b/MarkupString.Tests/Decoding/DisplayTests.cs
@@ -22,6 +22,33 @@ public async Task Resolve_PlainTextOutput_DropsEverything()
 		await Assert.That(style).IsEqualTo(DisplayStyle.Plain);
 	}
 
+	[Test]
+	public async Task Resolve_ReducesColours_ToWhatTheOutputShows()
+	{
+		var orange = AnsiMarkup.Create(foreground: new AnsiColor.Rgb(250, 130, 10), background: new AnsiColor.Rgb(10, 10, 120));
+		var sixteen = new DisplayOptions { Capabilities = OutputCapabilities.Browser with { Colors = ColorLevel.Standard } };
+		var xterm = new DisplayOptions { Capabilities = OutputCapabilities.Browser with { Colors = ColorLevel.Xterm256 } };
+
+		var reduced = AnsiDisplay.Default.Resolve(MarkupSet.Of(orange), sixteen);
+		await Assert.That(reduced.Foreground).IsEqualTo(new RgbColor(255, 85, 85));
+		await Assert.That(reduced.Background).IsEqualTo(new RgbColor(0, 0, 170));
+
+		var cube = AnsiDisplay.Default.Resolve(MarkupSet.Of(orange), xterm);
+		await Assert.That(cube.Foreground).IsEqualTo(new RgbColor(255, 135, 0));
+		await Assert.That(cube.Background).IsEqualTo(new RgbColor(0, 0, 135));
+
+		var full = AnsiDisplay.Default.Resolve(MarkupSet.Of(orange), Browser);
+		await Assert.That(full.Foreground).IsEqualTo(new RgbColor(250, 130, 10));
+	}
+
+	[Test]
+	public async Task Resolve_LinkGroup_NamesTheInteraction()
+	{
+		var style = AnsiDisplay.Default.Resolve(MarkupSet.Of([new LinkGroupMarkup("inner"), Link, new LinkGroupMarkup("outer")]), Browser);
+		await Assert.That(style.Interaction).IsEqualTo(new Interaction(InteractionKind.Command, "look") { Group = "inner" });
+		await Assert.That(AnsiDisplay.Default.Resolve(MarkupSet.Of(new LinkGroupMarkup("alone")), Browser).Interaction).IsNull();
+	}
+
 	[Test]
 	public async Task Resolve_PromptBecomesCommand_WhenPromptsAreNotShown()
 	{
diff --git a/MarkupString.Tests/Decoding/PictureDecodingTests.cs b/MarkupString.Tests/Decoding/PictureDecodingTests.cs
index 80526bd..9dfcfa4 100644
--- a/MarkupString.Tests/Decoding/PictureDecodingTests.cs
+++ b/MarkupString.Tests/Decoding/PictureDecodingTests.cs
@@ -177,6 +177,61 @@ public async Task Kitty_Quiet_SendsNothing()
 		await Assert.That(replies).IsEqualTo(0);
 	}
 
+	[Test]
+	public async Task Kitty_MovingPicture_RoundTrip()
+	{
+		var red = RedBlue(2, 2).Rgba.ToArray();
+		var blue = red.Reverse().ToArray();
+		var picture = new TerminalPicture("moving", 2, 2,
+			[new TerminalPictureFrame(red, TimeSpan.FromMilliseconds(100)), new TerminalPictureFrame(blue, TimeSpan.FromMilliseconds(250))]);
+		var (lines, decoder) = Decode(Wire(TerminalFeatures.KittyGraphics | TerminalFeatures.MovingPictures, picture));
+
+		var image = lines.SelectMany(line => line.Content.Runs).SelectMany(run => run.Markups).OfType<ImageMarkup>().First();
+		await Assert.That(decoder.Pictures().TryGet(image, out var stored)).IsTrue();
+		await Assert.That(stored!.IsMoving).IsTrue();
+		var frames = stored.Pixels!.Frames;
+		await Assert.That(frames.Select(frame => frame.Duration.TotalMilliseconds)).IsEquivalentTo([100.0, 250.0]);
+		await Assert.That(frames[0].Rgba.ToArray()).IsEquivalentTo(red);
+		await Assert.That(frames[1].Rgba.ToArray()).IsEquivalentTo(blue);
+		await Assert.That(stored.MediaType).IsEqualTo("image/gif");
+		await Assert.That(stored.ToDataUrl()).StartsWith("data:image/gif;base64,R0lGOD");
+		await Assert.That(decoder.Diagnostics.PicturesFailed).IsEqualTo(0);
+	}
+
+	[Test]
+	public async Task Kitty_Frame_BlendsOverItsBase_AndEditsInPlace()
+	{
+		// A 2 × 1 black root frame; frame 2 puts half-transparent white over its right pixel; then frame 2's left pixel is
+		// replaced with red.
+		var decoder = Registry.CreateDecoder();
+		decoder.Feed($"\e_Ga=t,i=3,f=32,s=2,v=1;{Convert.ToBase64String([0, 0, 0, 255, 0, 0, 0, 255])}\e\\");
+		decoder.Feed($"\e_Ga=f,i=3,f=32,s=1,v=1,x=1,c=1,z=70;{Convert.ToBase64String([255, 255, 255, 128])}\e\\");
+		decoder.Feed($"\e_Ga=f,i=3,f=32,s=1,v=1,r=2,X=1;{Convert.ToBase64String([255, 0, 0, 255])}\e\\");
+		decoder.Feed("\e_Ga=a,i=3,r=1,z=500\e\\");
+
+		var stored = decoder.Pictures().TryGet(KeyOf(decoder), out var found) ? found : null;
+		var frames = stored!.Pixels!.Frames;
+		await Assert.That(frames.Count).IsEqualTo(2);
+		await Assert.That(frames[0].Rgba.ToArray()).IsEquivalentTo(new byte[] { 0, 0, 0, 255, 0, 0, 0, 255 });
+		await Assert.That(frames[1].Rgba.ToArray()).IsEquivalentTo(new byte[] { 255, 0, 0, 255, 128, 128, 128, 255 });
+		await Assert.That(frames.Select(frame => frame.Duration.TotalMilliseconds)).IsEquivalentTo([500.0, 70.0]);
+		await Assert.That(decoder.Diagnostics.PicturesFailed).IsEqualTo(0);
+	}
+
+	[Test]
+	public async Task Kitty_Frame_ForAnUnknownImage_Fails()
+	{
+		var decoder = Registry.CreateDecoder();
+		decoder.Feed($"\e_Ga=f,i=4,f=32,s=1,v=1;{Convert.ToBase64String(new byte[4])}\e\\");
+		await Assert.That(decoder.Diagnostics.PicturesFailed).IsEqualTo(1);
+	}
+
+	private static string KeyOf(Decoder decoder)
+	{
+		var placed = decoder.Feed("\e_Ga=p,i=3,c=2,r=1\e\\\n");
+		return placed.SelectMany(line => line.Content.Runs).SelectMany(run => run.Markups).OfType<ImageMarkup>().First().Source[PictureStore.Scheme.Length..];
+	}
+
 	[Test]
 	public async Task InlineImage_NotInline_IsADownload()
 	{
diff --git a/MarkupString.Tests/Decoding/VtDecodingTests.cs b/MarkupString.Tests/Decoding/VtDecodingTests.cs
index 08d7256..e5cb968 100644
--- a/MarkupString.Tests/Decoding/VtDecodingTests.cs
+++ b/MarkupString.Tests/Decoding/VtDecodingTests.cs
@@ -160,6 +160,18 @@ public async Task Osc8_MakesALink()
 		await Assert.That(spans[2].Style.Interaction).IsNull();
 	}
 
+	[Test]
+	public async Task Osc8_Id_GroupsTheLinkAcrossLines()
+	{
+		var lines = Decode("\e]8;foo=1:id=menu;https://example.com\e\\one\ntwo\e]8;;\e\\ three \e]8;;https://example.com\e\\x\e]8;;\e\\\n");
+		var first = Spans(lines[0].Content).Single().Style.Interaction;
+		var second = Spans(lines[1].Content);
+		await Assert.That(first).IsEqualTo(new Interaction(InteractionKind.Url, "https://example.com") { Group = "menu" });
+		await Assert.That(second[0].Style.Interaction).IsEqualTo(first);
+		await Assert.That(second[1].Style.Interaction).IsNull();
+		await Assert.That(second[2].Style.Interaction).IsEqualTo(new Interaction(InteractionKind.Url, "https://example.com"));
+	}
+
 	[Test]
 	public async Task Osc8_UnsafeScheme_IsText()
 	{
diff --git a/MarkupString/Display/DisplayRegistry.cs b/MarkupString/Display/DisplayRegistry.cs
index d29e925..25fac54 100644
--- a/MarkupString/Display/DisplayRegistry.cs
+++ b/MarkupString/Display/DisplayRegistry.cs
@@ -34,6 +34,17 @@ public DisplayStyle Resolve(MarkupSet? markups, DisplayOptions options)
 
 		var builder = new StyleBuilder();
 		foreach (var contributor in _contributors) contributor.Contribute(markups, builder, options);
+		if (builder.Interaction is { Group: null } interaction)
+		{
+			// The innermost group names the link, whichever contributor made it.
+			for (var i = 0; i < markups.Count; i++)
+			{
+				if (markups[i] is not LinkGroupMarkup group) continue;
+				builder.Interaction = interaction with { Group = group.Group };
+				break;
+			}
+		}
+
 		return Degrade(builder, options);
 	}
 
@@ -61,9 +72,13 @@ private static DisplayStyle Degrade(StyleBuilder style, DisplayOptions options)
 			}
 		}
 
+		var level = capabilities.Colors;
+		style.Background = Reduce(style.Background, level, options.Colors);
+		style.Foreground = Reduce(style.Foreground, level, options.Colors);
 		if (style.Foreground is { } foreground && options.Colors is { } resolver)
 		{
-			style.Foreground = resolver.Legible(foreground, style.Background ?? options.DefaultBackground);
+			// The client's change for legibility is reduced too, as the output can only show its palette.
+			style.Foreground = Reduce(resolver.Legible(foreground, style.Background ?? options.DefaultBackground), level, resolver);
 		}
 
 		if (style.Interaction is { } interaction) style.Interaction = Degrade(interaction, capabilities.Interactions);
@@ -73,6 +88,56 @@ private static DisplayStyle Degrade(StyleBuilder style, DisplayOptions options)
 		return style.Build();
 	}
 
+	/// <summary>
+	/// <paramref name="color"/> as an output of <paramref name="level"/> shows it: the nearest of its sixteen or 256
+	/// colours, by redmean distance, as <paramref name="resolver"/> draws them (or the xterm palette).
+	/// </summary>
+	private static RgbColor? Reduce(RgbColor? color, ColorLevel level, IColorResolver? resolver)
+	{
+		if (color is not { } rgb || level is not (ColorLevel.Standard or ColorLevel.Xterm256)) return color;
+		var count = level == ColorLevel.Standard ? 16 : 256;
+		var best = rgb;
+		var nearest = double.MaxValue;
+		for (var i = 0; i < count; i++)
+		{
+			var entry = Palette(i, resolver);
+			var distance = Redmean(rgb, entry);
+			if (distance >= nearest) continue;
+			(nearest, best) = (distance, entry);
+			if (distance == 0) break;
+		}
+
+		return best;
+	}
+
+	private static RgbColor Palette(int index, IColorResolver? resolver)
+	{
+		if (index < 16) return resolver?.Standard(index & 7, index >= 8) ?? ColorMath.StandardColor(index);
+		return resolver?.Xterm(index) ?? XtermColor(index);
+	}
+
+	private static ReadOnlySpan<byte> CubeLevels => [0, 95, 135, 175, 215, 255];
+
+	private static RgbColor XtermColor(int index)
+	{
+		if (index >= 232)
+		{
+			var grey = (byte)(8 + 10 * (index - 232));
+			return new RgbColor(grey, grey, grey);
+		}
+
+		var offset = index - 16;
+		return new RgbColor(CubeLevels[offset / 36], CubeLevels[offset / 6 % 6], CubeLevels[offset % 6]);
+	}
+
+	/// <summary>The "redmean" distance, squared: a cheap measure of how different two colours look.</summary>
+	private static double Redmean(RgbColor a, RgbColor b)
+	{
+		var mean = (a.R + b.R) / 2.0;
+		double r = a.R - b.R, g = a.G - b.G, bl = a.B - b.B;
+		return (2 + mean / 256) * r * r + 4 * g * g + (2 + (255 - mean) / 256) * bl * bl;
+	}
+
 	private static Interaction? Degrade(Interaction interaction, InteractionKinds allowed)
 	{
 		if (interaction.Choices is { Count: > 0 } && (allowed & InteractionKinds.Menu) == 0)
diff --git a/MarkupString/Elements/CommandMenuMarkup.cs b/MarkupString/Elements/CommandMenuMarkup.cs
index a83e67b..3ea63e2 100644
--- a/MarkupString/Elements/CommandMenuMarkup.cs
+++ b/MarkupString/Elements/CommandMenuMarkup.cs
@@ -38,3 +38,10 @@ public override int GetHashCode()
 /// </summary>
 /// <param name="Color">The background.</param>
 public sealed record HighlightMarkup(RgbColor Color) : IMarkup;
+
+/// <summary>
+/// Makes the link it wraps one link with every other stretch in the same group, even across lines, as an OSC 8
+/// <c>id</c> does. It becomes <see cref="Display.Interaction.Group"/>.
+/// </summary>
+/// <param name="Group">The group's name.</param>
+public sealed record LinkGroupMarkup(string Group) : IMarkup;
diff --git a/MarkupString/Elements/ElementCodecs.cs b/MarkupString/Elements/ElementCodecs.cs
index c0ceb85..1f2ba3c 100644
--- a/MarkupString/Elements/ElementCodecs.cs
+++ b/MarkupString/Elements/ElementCodecs.cs
@@ -140,6 +140,9 @@ internal static class ElementCodecs
 		new Codec<HighlightMarkup>("highlight",
 			static (w, m) => w.WriteString("c", $"#{m.Color.R:x2}{m.Color.G:x2}{m.Color.B:x2}"),
 			static e => new HighlightMarkup(Hex(String(e, "c")))),
+		new Codec<LinkGroupMarkup>("link-group",
+			static (w, m) => w.WriteString("g", m.Group),
+			static e => new LinkGroupMarkup(String(e, "g") ?? string.Empty)),
 		new Codec<StandInMarkup>("standin",
 			static (w, m) => w.WriteString("t", m.Text),
 			static e => new StandInMarkup(String(e, "t") ?? string.Empty)),
diff --git a/MarkupString/PublicAPI.Unshipped.txt b/MarkupString/PublicAPI.Unshipped.txt
index ae04b24..20eefc5 100644
--- a/MarkupString/PublicAPI.Unshipped.txt
+++ b/MarkupString/PublicAPI.Unshipped.txt
@@ -727,3 +727,15 @@ static MarkupString.Decoding.TagSyntax.Parse(System.ReadOnlySpan<char> body, Sys
 ~override MarkupString.Decoding.TagArgument.Equals(object obj) -> bool
 ~override MarkupString.Decoding.TagArgument.ToString() -> string
 MarkupString.Decoding.DecodeContext.LineIsEmpty.get -> bool
+MarkupString.LinkGroupMarkup
+MarkupString.LinkGroupMarkup.<Clone>$() -> MarkupString.LinkGroupMarkup!
+MarkupString.LinkGroupMarkup.Deconstruct(out string! Group) -> void
+MarkupString.LinkGroupMarkup.Equals(MarkupString.LinkGroupMarkup? other) -> bool
+MarkupString.LinkGroupMarkup.Group.get -> string!
+MarkupString.LinkGroupMarkup.Group.init -> void
+MarkupString.LinkGroupMarkup.LinkGroupMarkup(string! Group) -> void
+override MarkupString.LinkGroupMarkup.Equals(object? obj) -> bool
+override MarkupString.LinkGroupMarkup.GetHashCode() -> int
+override MarkupString.LinkGroupMarkup.ToString() -> string!
+static MarkupString.LinkGroupMarkup.operator !=(MarkupString.LinkGroupMarkup? left, MarkupString.LinkGroupMarkup? right) -> bool
+static MarkupString.LinkGroupMarkup.operator ==(MarkupString.LinkGroupMarkup? left, MarkupString.LinkGroupMarkup? right) -> bool
diff --git a/docs/decoding.md b/docs/decoding.md
index e8631b4..356e4b1 100644
--- a/docs/decoding.md
+++ b/docs/decoding.md
@@ -177,12 +177,12 @@ Decoder.DecodeAll("\e(0lqqk\e(B ok", registry)[0].Content;  // ┌──┐ ok
 | `10`, `11`, `12` | Set the foreground, background, cursor colour, or answer `?` (10 and 11 only). `10;a;b` sets 10 and 11 at once. |
 | `110`, `111`, `112` | Reset them |
 | `52;sel;base64` | `ClipboardEvent` with the decoded text, or a null text for `?`. Invalid base64 is dropped. |
-| `8;params;uri` | A link over the text that follows, until an empty uri. An address longer than 2083 characters, or one `UrlSafety.IsSafeNavigableUrl` refuses (`javascript:` and the like), ends the link instead. |
+| `8;params;uri` | A link over the text that follows, until an empty uri. An address longer than 2083 characters, or one `UrlSafety.IsSafeNavigableUrl` refuses (`javascript:` and the like), ends the link instead. An `id=` among the params becomes a `LinkGroupMarkup`, and so `Interaction.Group`: the text under it is one link even across lines. |
 | `68;1;SEND;command` | An MSLP command link over the underlined text that follows. Turning the underline off ends it, and so does the end of the line. |
 
 Colours are X11 specs: `rgb:r/g/b` with one to four hex digits a channel, or `#rgb`, `#rrggbb`,
 `#rrrgggbbb`, `#rrrrggggbbbb`. `OscPlugin.ParseColor` and `FormatColor` are public. Links are
-written under the `VtPens.Link` pen.
+written under the `VtPens.Link` pen, an OSC 8 `id` under `VtPens.LinkGroup`.
 
 ### `AnswersPlugin`
 
@@ -514,8 +514,13 @@ Kitty specifics:
 
 - Only `t=d` (the picture in the sequence) is read. A file, temporary file or shared memory is
   refused with `EINVAL`, since the server's files are not the client's.
-- `a=t`, `a=T`, `a=p`, `a=q` and `a=d` are read; animation frames are not, so a moving picture is its
-  first frame.
+- `a=t`, `a=T`, `a=p`, `a=q` and `a=d` are read, and so are animation frames. `a=f` adds a frame,
+  or edits frame `r`: built on a copy of frame `c` (or a blank filled with `Y`), its data put at `x`,
+  `y` and blended over what is there unless `X=1`, shown for `z` ms (40 unless given). `a=a` with `r`
+  and `z` sets a frame's time. Playing, stopping and looping are left to the client, and so is
+  composing (`a=c`), which is counted as unhandled. At most `PicturesPlugin.MaxFrames` (1000) frames
+  are kept. A picture with frames is a `StoredPicture` whose `IsMoving` is true; its `Pixels.Frames`
+  grow as frames arrive, and `Encoded` and `ToDataUrl()` give it as a looping GIF.
 - Unicode placeholders (U+10EEEE with row and column diacritics, the image id in the foreground
   colour) draw a picture transmitted with `U=1`. That is how this package's writer sends Kitty
   pictures, so its output reads back cell for cell.
diff --git a/docs/display.md b/docs/display.md
index 57163dc..774040b 100644
--- a/docs/display.md
+++ b/docs/display.md
@@ -176,13 +176,17 @@ var text = Decoder.DecodeAll("\e[31mred\e[0m \e[34;44msame\e[0m", decoders)[0].C
 
 `Resolve` drops what the output cannot show, in this order:
 
-- **Colours.** At `ColorLevel.Attributes` or `None` both colours are dropped. Above that, every colour
-  is already RGB, so the level does not reduce it further here.
+- **Colours.** At `ColorLevel.Attributes` or `None` both colours are dropped. At `Standard` each colour
+  becomes the nearest of the sixteen, and at `Xterm256` the nearest of the 256 (after the inverse swap
+  below), by redmean distance, as `Colors` draws them (the xterm palette when it is null). The colour
+  `Legible` returns is reduced the same way. At `TrueColor` RGB passes through.
 - **Attributes.** Those the output lacks are dropped. At `ColorLevel.None` every attribute is.
 - **Prompts.** A `CommandMenuMarkup` with `Prompt` set is a `Prompt` interaction.
 - **Inverse.** With colour, foreground and background are swapped, filling in `DefaultForeground` and
   `DefaultBackground`; `Inverse` stays set for information. At `Attributes` the flag is kept for the
   output to draw when it has `TextAttributes.Inverse`, and dropped when it does not.
+- **Link groups.** A `LinkGroupMarkup` (as an OSC 8 `id` makes) sets the `Group` of the interaction
+  it is over, the innermost winning, whichever contributor made the link.
 - **Interactions.** Menu choices go when the output has no `Menu`. A prompt link becomes a command
   link on an output with `Command` but not `Prompt`. Any other interaction the output lacks is dropped,
   and the text stays.

From 88d96c5728a86c1129d56a904afc94fabead2e06 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 23:08:39 +0000
Subject: [PATCH 16/19] Let a host inject the picture cache

IPictureCache holds decoded pictures by content key; MemoryPictureCache is the
thread-safe LRU default. WithPictures(cache) shares one between decoders, so a
picture sent to many connections is decoded and kept once, and a file already
held is not decoded again. Frames go on a per-connection copy so a shared
still picture never changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rqqt7WGskvSsoRXvKMqybx
---
 CHANGELOG.md                                  |   2 +
 MarkupString.Ansi/Decoding/PictureStore.cs    | 236 ++++++++++++++----
 MarkupString.Ansi/Decoding/PicturesPlugin.cs  |  85 +++++--
 MarkupString.Ansi/PublicAPI.Unshipped.txt     |  21 +-
 .../Decoding/PictureDecodingTests.cs          |  75 +++++-
 docs/decoding.md                              |  18 +-
 6 files changed, 364 insertions(+), 73 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 10765f9..4778ffd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,6 +33,8 @@ follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   models. See [Display](docs/display.md).
 - `CommandMenuMarkup` (a menu of commands, or a prompt), `HighlightMarkup` (a background) and `LinkGroupMarkup`
   (an OSC 8 `id`, which becomes `Interaction.Group`) in core, with codecs.
+- `IPictureCache` and `MemoryPictureCache`: `WithPictures(cache)` shares decoded pictures between connections, and a
+  host can keep them in a cache of its own.
 - Kitty animation frames (`a=f`, and frame times with `a=a`) decode into a moving `StoredPicture`, given as a GIF.
 - Spans and cells at `ColorLevel.Standard` or `Xterm256` get the nearest colour of that palette.
 - `AnsiStyle.Concealed` (SGR 8), written as SGR 8 and as `ms-conceal` in HTML.
diff --git a/MarkupString.Ansi/Decoding/PictureStore.cs b/MarkupString.Ansi/Decoding/PictureStore.cs
index 9937486..6b1432e 100644
--- a/MarkupString.Ansi/Decoding/PictureStore.cs
+++ b/MarkupString.Ansi/Decoding/PictureStore.cs
@@ -82,36 +82,173 @@ internal static long PixelBytes(TerminalPicture? pixels) =>
 }
 
 /// <summary>
-/// The pictures one connection's decoder read, within a budget of bytes; the least recently used go first. It is
-/// also the <see cref="ITerminalPictureSource"/> that draws them again in a terminal. Get a decoder's with
+/// Where decoded pictures are kept, by <see cref="StoredPicture.Key"/>: a hash of the picture, so the same picture
+/// is kept once however often, and by however many connections, it is sent. Give one to
+/// <see cref="PictureDecoding.WithPictures(MarkupString.Decoding.DecoderRegistry, IPictureCache)"/> to share it
+/// between connections, or to keep pictures somewhere of your own. <see cref="MemoryPictureCache"/> is the default.
+/// </summary>
+/// <remarks>
+/// Decoders on different threads may share one cache, so an implementation must be safe to call from several
+/// threads at once. A picture is not changed once it is in a cache, except one that a connection made for its own
+/// moving picture, under a key of its own; <see cref="Set"/> is called again when that one gains a frame.
+/// </remarks>
+public interface IPictureCache
+{
+	/// <summary>The picture with <paramref name="key"/>, if it is held.</summary>
+	bool TryGet(string key, [NotNullWhen(true)] out StoredPicture? picture);
+
+	/// <summary>Holds <paramref name="picture"/>, or takes note that its <see cref="StoredPicture.Size"/> changed.</summary>
+	void Set(StoredPicture picture);
+
+	/// <summary>Forgets the picture with <paramref name="key"/>.</summary>
+	bool Remove(string key);
+}
+
+/// <summary>Pictures in memory, within a budget of bytes; the least recently used go first. Safe to share.</summary>
+public sealed class MemoryPictureCache : IPictureCache
+{
+	private sealed class Entry(StoredPicture picture)
+	{
+		public StoredPicture Picture { get; } = picture;
+
+		public long Size { get; set; }
+	}
+
+	private readonly Dictionary<string, LinkedListNode<Entry>> _pictures = new(StringComparer.Ordinal);
+	private readonly LinkedList<Entry> _order = [];
+	private readonly Lock _lock = new();
+	private long _budget = 64L * 1024 * 1024;
+
+	/// <summary>The most bytes held. 64 MiB unless set.</summary>
+	public long Budget
+	{
+		get => _budget;
+		set
+		{
+			lock (_lock)
+			{
+				_budget = value;
+				Evict(null);
+			}
+		}
+	}
+
+	/// <summary>The bytes held now.</summary>
+	public long Used { get; private set; }
+
+	/// <summary>The pictures held now.</summary>
+	public int Count
+	{
+		get
+		{
+			lock (_lock) return _pictures.Count;
+		}
+	}
+
+	/// <inheritdoc/>
+	public bool TryGet(string key, [NotNullWhen(true)] out StoredPicture? picture)
+	{
+		ArgumentNullException.ThrowIfNull(key);
+		lock (_lock)
+		{
+			if (_pictures.TryGetValue(key, out var node))
+			{
+				_order.Remove(node);
+				_order.AddFirst(node);
+				picture = node.Value.Picture;
+				return true;
+			}
+		}
+
+		picture = null;
+		return false;
+	}
+
+	/// <inheritdoc/>
+	public void Set(StoredPicture picture)
+	{
+		ArgumentNullException.ThrowIfNull(picture);
+		lock (_lock)
+		{
+			if (_pictures.TryGetValue(picture.Key, out var node))
+			{
+				_order.Remove(node);
+				Used -= node.Value.Size;
+			}
+			else
+			{
+				node = new LinkedListNode<Entry>(new Entry(picture));
+				_pictures[picture.Key] = node;
+			}
+
+			node.Value.Size = picture.Size;
+			Used += node.Value.Size;
+			_order.AddFirst(node);
+			Evict(picture);
+		}
+	}
+
+	/// <inheritdoc/>
+	public bool Remove(string key)
+	{
+		ArgumentNullException.ThrowIfNull(key);
+		lock (_lock) return RemoveHeld(key);
+	}
+
+	private bool RemoveHeld(string key)
+	{
+		if (!_pictures.Remove(key, out var node)) return false;
+		_order.Remove(node);
+		Used -= node.Value.Size;
+		return true;
+	}
+
+	/// <summary>Drops the least recently used until the budget is met, keeping the newest and <paramref name="keep"/>.</summary>
+	private void Evict(StoredPicture? keep)
+	{
+		while (Used > _budget && _order.Count > 1 && _order.Last!.Value.Picture != keep) RemoveHeld(_order.Last.Value.Picture.Key);
+	}
+}
+
+/// <summary>
+/// The pictures one connection's decoder read, kept in an <see cref="IPictureCache"/>. It is also the
+/// <see cref="ITerminalPictureSource"/> that draws them again in a terminal. Get a decoder's with
 /// <see cref="PicturesPlugin.Pictures(MarkupString.Decoding.Decoder)"/>.
 /// </summary>
 /// <remarks>
 /// A picture the server deletes (Kitty <c>a=d</c>) is only forgotten by its id: lines already read still show it,
-/// until the budget pushes it out. A line whose picture is gone shows its text instead.
+/// until the cache lets it go. A line whose picture is gone shows its text instead.
 /// </remarks>
 public sealed class PictureStore : ITerminalPictureSource
 {
 	/// <summary>The scheme of a <see cref="StoredPicture.Source"/>.</summary>
 	public const string Scheme = "picture:";
 
-	private readonly Dictionary<string, LinkedListNode<StoredPicture>> _pictures = new(StringComparer.Ordinal);
-	private readonly LinkedList<StoredPicture> _order = [];
+	private readonly HashSet<string> _read = new(StringComparer.Ordinal);
 	private readonly HashSet<uint> _transmitted = [];
 
-	/// <summary>The most bytes held. 64 MiB unless set.</summary>
-	public long Budget { get; set; } = 64L * 1024 * 1024;
+	/// <summary>A store of its own, in a new <see cref="MemoryPictureCache"/>.</summary>
+	public PictureStore()
+		: this(null)
+	{
+	}
+
+	/// <summary>A store that keeps its pictures in <paramref name="cache"/>, or in a new <see cref="MemoryPictureCache"/>.</summary>
+	public PictureStore(IPictureCache? cache) => Cache = cache ?? new MemoryPictureCache();
+
+	/// <summary>Where the pictures are kept.</summary>
+	public IPictureCache Cache { get; }
 
 	/// <summary>The largest picture decoded, in pixels.</summary>
 	public long MaxPixels { get; set; } = 4096L * 4096;
 
-	/// <summary>The bytes held now.</summary>
-	public long Used { get; private set; }
-
-	/// <summary>The pictures held now.</summary>
-	public int Count => _pictures.Count;
+	/// <summary>How many pictures this connection has read, held or not.</summary>
+	public int Count => _read.Count;
 
-	/// <summary>Raised when a picture is stored, so a host can serve it from an address of its own.</summary>
+	/// <summary>
+	/// Raised when a picture is first stored, so a host can serve it from an address of its own. One already in a
+	/// shared cache is not raised again.
+	/// </summary>
 	public event Action<StoredPicture>? Added;
 
 	/// <summary>Stores decoded pixels.</summary>
@@ -120,40 +257,27 @@ public sealed class PictureStore : ITerminalPictureSource
 	/// <summary>Stores a file, with its pixels when they were decoded.</summary>
 	public StoredPicture Add(int width, int height, byte[]? rgba, ReadOnlyMemory<byte> encoded, string? mediaType)
 	{
-		var key = Hash(encoded.IsEmpty ? rgba : encoded.Span);
-		if (_pictures.TryGetValue(key, out var existing))
-		{
-			_order.Remove(existing);
-			_order.AddFirst(existing);
-			return existing.Value;
-		}
+		var key = KeyOf(encoded.IsEmpty ? rgba : encoded.Span);
+		_read.Add(key);
+		if (Cache.TryGet(key, out var existing)) return existing;
 
 		var pixels = rgba is null ? null : new TerminalPicture(key, width, height, rgba);
 		var picture = new StoredPicture(key, width, height, pixels, encoded, mediaType);
-		_pictures[key] = _order.AddFirst(picture);
-		Used += picture.Size;
-		while (Used > Budget && _order.Count > 1) Remove(_order.Last!.Value.Key);
+		Cache.Set(picture);
 		Added?.Invoke(picture);
 		return picture;
 	}
 
-	/// <summary>Replaces a held picture's pixels, as when a moving picture gains a frame.</summary>
-	internal void ReplacePixels(StoredPicture picture, TerminalPicture pixels)
-	{
-		var held = _pictures.ContainsKey(picture.Key);
-		if (held) Used -= picture.Size;
-		picture.ReplacePixels(pixels);
-		if (!held) return;
-		Used += picture.Size;
-		while (Used > Budget && _order.Count > 1 && _order.Last!.Value != picture) Remove(_order.Last.Value.Key);
-	}
-
-	/// <summary>The picture with <paramref name="key"/>, if it is still held.</summary>
-	public bool TryGet(string key, [NotNullWhen(true)] out StoredPicture? picture)
+	/// <summary>
+	/// The picture already held for the file <paramref name="encoded"/>, so it need not be decoded again; never one
+	/// larger than <see cref="MaxPixels"/>.
+	/// </summary>
+	internal bool TryGetFile(ReadOnlySpan<byte> encoded, [NotNullWhen(true)] out StoredPicture? picture)
 	{
-		if (_pictures.TryGetValue(key, out var node))
+		var key = KeyOf(encoded);
+		if (Cache.TryGet(key, out picture) && (long)picture.Width * picture.Height <= MaxPixels)
 		{
-			picture = node.Value;
+			_read.Add(key);
 			return true;
 		}
 
@@ -161,6 +285,31 @@ public bool TryGet(string key, [NotNullWhen(true)] out StoredPicture? picture)
 		return false;
 	}
 
+	/// <summary>
+	/// A copy of <paramref name="still"/> under a key of its own, for this connection to add frames to, so the
+	/// still picture, which other lines and connections may show, stays as it is.
+	/// </summary>
+	internal StoredPicture Fork(StoredPicture still)
+	{
+		var key = $"{still.Key}-{Guid.NewGuid():N}";
+		var pixels = still.Pixels is { } source ? new TerminalPicture(key, source.Width, source.Height, source.Rgba) : null;
+		var picture = new StoredPicture(key, still.Width, still.Height, pixels, default, null);
+		_read.Add(key);
+		Cache.Set(picture);
+		Added?.Invoke(picture);
+		return picture;
+	}
+
+	/// <summary>Replaces a picture's pixels, as when a moving picture gains a frame.</summary>
+	internal void ReplacePixels(StoredPicture picture, TerminalPicture pixels)
+	{
+		picture.ReplacePixels(pixels);
+		if (Cache.TryGet(picture.Key, out var held) && held == picture) Cache.Set(picture);
+	}
+
+	/// <summary>The picture with <paramref name="key"/>, if it is still held.</summary>
+	public bool TryGet(string key, [NotNullWhen(true)] out StoredPicture? picture) => Cache.TryGet(key, out picture);
+
 	/// <summary>The picture <paramref name="image"/> shows, if it is one of these and still held.</summary>
 	public bool TryGet(ImageMarkup image, [NotNullWhen(true)] out StoredPicture? picture)
 	{
@@ -169,13 +318,11 @@ public bool TryGet(ImageMarkup image, [NotNullWhen(true)] out StoredPicture? pic
 		return image.Source.StartsWith(Scheme, StringComparison.Ordinal) && TryGet(image.Source[Scheme.Length..], out picture);
 	}
 
-	/// <summary>Forgets the picture with <paramref name="key"/>.</summary>
+	/// <summary>Forgets the picture with <paramref name="key"/>, for every connection that shares the cache.</summary>
 	public bool Remove(string key)
 	{
-		if (!_pictures.Remove(key, out var node)) return false;
-		_order.Remove(node);
-		Used -= node.Value.Size;
-		return true;
+		_read.Remove(key);
+		return Cache.Remove(key);
 	}
 
 	/// <inheritdoc/>
@@ -188,7 +335,8 @@ public bool TryGetPicture(ImageMarkup image, [NotNullWhen(true)] out TerminalPic
 	/// <inheritdoc/>
 	public bool MarkTransmitted(uint imageId) => _transmitted.Add(imageId);
 
-	private static string Hash(ReadOnlySpan<byte> data)
+	/// <summary>The key of a picture whose file, or else pixels, are <paramref name="data"/>.</summary>
+	internal static string KeyOf(ReadOnlySpan<byte> data)
 	{
 		Span<byte> hash = stackalloc byte[32];
 		SHA256.HashData(data, hash);
diff --git a/MarkupString.Ansi/Decoding/PicturesPlugin.cs b/MarkupString.Ansi/Decoding/PicturesPlugin.cs
index db530c9..30e6373 100644
--- a/MarkupString.Ansi/Decoding/PicturesPlugin.cs
+++ b/MarkupString.Ansi/Decoding/PicturesPlugin.cs
@@ -29,12 +29,14 @@ public sealed class PicturesPlugin : IDecoderPlugin
 
 	private static readonly Dictionary<int, int> DiacriticIndex = BuildDiacriticIndex();
 
-	/// <summary>The one instance.</summary>
-	public static PicturesPlugin Instance { get; } = new();
+	/// <summary>The instance that gives each connection a cache of its own.</summary>
+	public static PicturesPlugin Instance { get; } = new(null);
 
-	private PicturesPlugin()
-	{
-	}
+	/// <summary>The plugin with every connection's pictures kept in <paramref name="cache"/>, or each in its own when null.</summary>
+	public PicturesPlugin(IPictureCache? cache) => Cache = cache;
+
+	/// <summary>The cache every connection's pictures are kept in, or null for one each.</summary>
+	public IPictureCache? Cache { get; }
 
 	/// <inheritdoc/>
 	public string Name => "pictures";
@@ -43,7 +45,16 @@ private PicturesPlugin()
 	public static PictureStore Pictures(Decoder decoder)
 	{
 		ArgumentNullException.ThrowIfNull(decoder);
-		return decoder.State<PictureState>().Store;
+		var state = decoder.State<PictureState>();
+		state.Bind(decoder.Registry.Plugins.OfType<PicturesPlugin>().FirstOrDefault()?.Cache);
+		return state.Store;
+	}
+
+	private PictureState Bind(DecodeContext context)
+	{
+		var state = context.State<PictureState>();
+		state.Bind(Cache);
+		return state;
 	}
 
 	/// <inheritdoc/>
@@ -51,11 +62,15 @@ public void Register(DecoderBuilder builder)
 	{
 		ArgumentNullException.ThrowIfNull(builder);
 		builder
-			.OnApc(static (payload, context) => payload.Length > 0 && payload[0] == 'G' && Kitty(payload[1..], context))
-			.OnOsc(1337, static (payload, context) => InlineImage(payload, context))
-			.OnDcs('q', static (in CsiSequence header, ReadOnlySpan<char> data, DecodeContext context) => Sixel(header, data, context))
-			.OnPrint(static (text, context) => Placeholders(text, context))
-			.OnLineEnd(static context => DrawOverlays(context));
+			.OnApc((payload, context) => payload.Length > 0 && payload[0] == 'G' && Bind(context) is not null && Kitty(payload[1..], context))
+			.OnOsc(1337, (payload, context) => Bind(context) is not null && InlineImage(payload, context))
+			.OnDcs('q', (in CsiSequence header, ReadOnlySpan<char> data, DecodeContext context) => Bind(context) is not null && Sixel(header, data, context))
+			.OnPrint((text, context) => Bind(context) is not null && Placeholders(text, context))
+			.OnLineEnd(context =>
+			{
+				Bind(context);
+				DrawOverlays(context);
+			});
 	}
 
 	// ── Kitty ───────────────────────────────────────────────────────────────────
@@ -180,14 +195,12 @@ private static void Complete(KittyKeys keys, string base64, DecodeContext contex
 
 	private static StoredPicture? DecodeKitty(KittyKeys keys, byte[] bytes, PictureStore store)
 	{
+		// A file already held is not decoded again.
+		if (keys.Format == 100 && store.TryGetFile(bytes, out var held) && held.Pixels is not null) return held;
 		if (DecodePixels(keys, bytes, store.MaxPixels) is not { } pixels) return null;
-		var picture = keys.Format == 100
+		return keys.Format == 100
 			? store.Add(pixels.Width, pixels.Height, pixels.Rgba, bytes, "image/png")
 			: store.Add(pixels.Width, pixels.Height, pixels.Rgba);
-
-		// The same picture sent again starts over as one frame; its frames follow again if it moves.
-		if (picture.IsMoving) store.ReplacePixels(picture, new TerminalPicture(picture.Key, pixels.Width, pixels.Height, pixels.Rgba));
-		return picture;
 	}
 
 	/// <summary>The pixels a Kitty transmission carries: a PNG, or raw RGB or RGBA <c>s</c> × <c>v</c>.</summary>
@@ -238,7 +251,7 @@ private static bool AddFrame(KittyKeys keys, (int Width, int Height, byte[] Rgba
 			return false;
 		}
 
-		var animation = Animation(keys.Id, stored, pixels, state);
+		var animation = Animation(keys.Id, ref stored, pixels, state);
 		var size = stored.Width * stored.Height * 4;
 
 		// For a frame, c and r are frame numbers (from 1), not cells.
@@ -298,15 +311,19 @@ private static void Animate(KittyKeys keys, PictureState state)
 
 		var frame = keys.Rows;
 		if (frame <= 0 || keys.Gap == 0) return;
-		var animation = Animation(keys.Id, stored, pixels, state);
+		var animation = Animation(keys.Id, ref stored, pixels, state);
 		if (frame > animation.Frames.Count) return;
 		animation.Gaps[frame - 1] = keys.Gap;
 		Publish(stored, animation, state.Store);
 	}
 
-	private static KittyAnimation Animation(uint id, StoredPicture stored, TerminalPicture pixels, PictureState state)
+	private static KittyAnimation Animation(uint id, ref StoredPicture stored, TerminalPicture pixels, PictureState state)
 	{
 		if (state.Animations.TryGetValue(id, out var animation)) return animation;
+
+		// Frames go on a copy of its own, so the still picture, shown elsewhere too, stays still.
+		stored = state.Store.Fork(stored);
+		state.KittyImages[id] = state.KittyImages[id] with { Key = stored.Key };
 		animation = new KittyAnimation();
 		if (pixels.Frames.Count > 0)
 		{
@@ -571,7 +588,12 @@ private static void ShowInlineImage(InlineArguments arguments, byte[]? bytes, De
 
 		var store = context.State<PictureState>().Store;
 		StoredPicture? picture = null;
-		if (PngDecoder.TryDecode(bytes, store.MaxPixels, out var width, out var height, out var rgba))
+		if (store.TryGetFile(bytes, out var held))
+		{
+			// A file already held is not decoded again.
+			picture = held;
+		}
+		else if (PngDecoder.TryDecode(bytes, store.MaxPixels, out var width, out var height, out var rgba))
 		{
 			picture = store.Add(width, height, rgba, bytes, "image/png");
 		}
@@ -929,7 +951,17 @@ public static InlineArguments Parse(ReadOnlySpan<char> text)
 /// <summary>The pictures plugin's state for one decoder.</summary>
 internal sealed class PictureState
 {
-	public PictureStore Store { get; } = new();
+	private IPictureCache? _cache;
+	private PictureStore? _store;
+
+	/// <summary>This connection's store, in the plugin's cache when it has one.</summary>
+	public PictureStore Store => _store ??= new PictureStore(_cache);
+
+	/// <summary>Takes the plugin's cache, before the store is first made.</summary>
+	public void Bind(IPictureCache? cache)
+	{
+		if (_store is null) _cache = cache;
+	}
 
 	public Dictionary<uint, PicturesPlugin.KittyImage> KittyImages { get; } = [];
 
@@ -958,6 +990,17 @@ public static DecoderRegistry WithPictures(this DecoderRegistry registry)
 		return registry.With(PicturesPlugin.Instance);
 	}
 
+	/// <summary>
+	/// The registry with <see cref="PicturesPlugin"/>, every decoder it makes keeping its pictures in
+	/// <paramref name="cache"/>: a picture several connections are sent is decoded and kept once.
+	/// </summary>
+	public static DecoderRegistry WithPictures(this DecoderRegistry registry, IPictureCache cache)
+	{
+		ArgumentNullException.ThrowIfNull(registry);
+		ArgumentNullException.ThrowIfNull(cache);
+		return registry.With(new PicturesPlugin(cache));
+	}
+
 	/// <summary>The pictures <paramref name="decoder"/> has read.</summary>
 	public static PictureStore Pictures(this Decoder decoder) => PicturesPlugin.Pictures(decoder);
 }
diff --git a/MarkupString.Ansi/PublicAPI.Unshipped.txt b/MarkupString.Ansi/PublicAPI.Unshipped.txt
index 090122a..9288248 100644
--- a/MarkupString.Ansi/PublicAPI.Unshipped.txt
+++ b/MarkupString.Ansi/PublicAPI.Unshipped.txt
@@ -57,8 +57,6 @@ MarkupString.Ansi.Decoding.PictureStore
 MarkupString.Ansi.Decoding.PictureStore.Add(int width, int height, byte[]! rgba) -> MarkupString.Ansi.Decoding.StoredPicture!
 MarkupString.Ansi.Decoding.PictureStore.Add(int width, int height, byte[]? rgba, System.ReadOnlyMemory<byte> encoded, string? mediaType) -> MarkupString.Ansi.Decoding.StoredPicture!
 MarkupString.Ansi.Decoding.PictureStore.Added -> System.Action<MarkupString.Ansi.Decoding.StoredPicture!>?
-MarkupString.Ansi.Decoding.PictureStore.Budget.get -> long
-MarkupString.Ansi.Decoding.PictureStore.Budget.set -> void
 MarkupString.Ansi.Decoding.PictureStore.Count.get -> int
 MarkupString.Ansi.Decoding.PictureStore.MarkTransmitted(uint imageId) -> bool
 MarkupString.Ansi.Decoding.PictureStore.MaxPixels.get -> long
@@ -68,7 +66,6 @@ MarkupString.Ansi.Decoding.PictureStore.Remove(string! key) -> bool
 MarkupString.Ansi.Decoding.PictureStore.TryGet(MarkupString.ImageMarkup! image, out MarkupString.Ansi.Decoding.StoredPicture? picture) -> bool
 MarkupString.Ansi.Decoding.PictureStore.TryGet(string! key, out MarkupString.Ansi.Decoding.StoredPicture? picture) -> bool
 MarkupString.Ansi.Decoding.PictureStore.TryGetPicture(MarkupString.ImageMarkup! image, out MarkupString.Ansi.TerminalPicture? picture) -> bool
-MarkupString.Ansi.Decoding.PictureStore.Used.get -> long
 MarkupString.Ansi.Decoding.PicturesPlugin
 MarkupString.Ansi.Decoding.PicturesPlugin.Name.get -> string!
 MarkupString.Ansi.Decoding.PicturesPlugin.Register(MarkupString.Decoding.DecoderBuilder! builder) -> void
@@ -92,3 +89,21 @@ MarkupString.Ansi.Decoding.StoredPicture.IsMoving.get -> bool
 MarkupString.Ansi.Decoding.StoredPicture.MediaType.get -> string!
 const MarkupString.Ansi.Decoding.PicturesPlugin.MaxFrames = 1000 -> int
 const MarkupString.Ansi.Decoding.VtPens.LinkGroup = "link-group" -> string!
+MarkupString.Ansi.Decoding.IPictureCache
+MarkupString.Ansi.Decoding.IPictureCache.Remove(string! key) -> bool
+MarkupString.Ansi.Decoding.IPictureCache.Set(MarkupString.Ansi.Decoding.StoredPicture! picture) -> void
+MarkupString.Ansi.Decoding.IPictureCache.TryGet(string! key, out MarkupString.Ansi.Decoding.StoredPicture? picture) -> bool
+MarkupString.Ansi.Decoding.MemoryPictureCache
+MarkupString.Ansi.Decoding.MemoryPictureCache.Budget.get -> long
+MarkupString.Ansi.Decoding.MemoryPictureCache.Budget.set -> void
+MarkupString.Ansi.Decoding.MemoryPictureCache.Count.get -> int
+MarkupString.Ansi.Decoding.MemoryPictureCache.MemoryPictureCache() -> void
+MarkupString.Ansi.Decoding.MemoryPictureCache.Remove(string! key) -> bool
+MarkupString.Ansi.Decoding.MemoryPictureCache.Set(MarkupString.Ansi.Decoding.StoredPicture! picture) -> void
+MarkupString.Ansi.Decoding.MemoryPictureCache.TryGet(string! key, out MarkupString.Ansi.Decoding.StoredPicture? picture) -> bool
+MarkupString.Ansi.Decoding.MemoryPictureCache.Used.get -> long
+MarkupString.Ansi.Decoding.PictureStore.Cache.get -> MarkupString.Ansi.Decoding.IPictureCache!
+MarkupString.Ansi.Decoding.PictureStore.PictureStore(MarkupString.Ansi.Decoding.IPictureCache? cache) -> void
+MarkupString.Ansi.Decoding.PicturesPlugin.Cache.get -> MarkupString.Ansi.Decoding.IPictureCache?
+MarkupString.Ansi.Decoding.PicturesPlugin.PicturesPlugin(MarkupString.Ansi.Decoding.IPictureCache? cache) -> void
+static MarkupString.Ansi.Decoding.PictureDecoding.WithPictures(this MarkupString.Decoding.DecoderRegistry! registry, MarkupString.Ansi.Decoding.IPictureCache! cache) -> MarkupString.Decoding.DecoderRegistry!
diff --git a/MarkupString.Tests/Decoding/PictureDecodingTests.cs b/MarkupString.Tests/Decoding/PictureDecodingTests.cs
index 9dfcfa4..800b8f8 100644
--- a/MarkupString.Tests/Decoding/PictureDecodingTests.cs
+++ b/MarkupString.Tests/Decoding/PictureDecodingTests.cs
@@ -261,12 +261,83 @@ public async Task InlineImage_Gif_IsKeptForABrowser()
 	[Test]
 	public async Task Store_EvictsTheLeastRecentlyUsed()
 	{
-		var store = new PictureStore { Budget = 100 };
+		var cache = new MemoryPictureCache { Budget = 100 };
+		var store = new PictureStore(cache);
 		var first = store.Add(4, 4, new byte[64]);
 		var second = store.Add(4, 4, Enumerable.Repeat((byte)1, 64).ToArray());
 		await Assert.That(store.TryGet(first.Key, out _)).IsFalse();
 		await Assert.That(store.TryGet(second.Key, out _)).IsTrue();
-		await Assert.That(store.Used).IsEqualTo(64);
+		await Assert.That(cache.Used).IsEqualTo(64);
+	}
+
+	[Test]
+	public async Task SharedCache_DecodesTheSamePictureOnce()
+	{
+		var cache = new MemoryPictureCache();
+		var registry = VtDecoding.Terminal.WithPictures(cache);
+		var wire = Wire(TerminalFeatures.KittyGraphics, RedBlue());
+		var first = registry.CreateDecoder();
+		var second = registry.CreateDecoder();
+		var added = 0;
+		first.Pictures().Added += _ => added++;
+		second.Pictures().Added += _ => added++;
+
+		first.Feed(wire);
+		second.Feed(wire);
+
+		await Assert.That(first.Pictures().Cache).IsSameReferenceAs(cache);
+		await Assert.That(cache.Count).IsEqualTo(1);
+		await Assert.That(added).IsEqualTo(1);
+		await Assert.That(second.Pictures().Count).IsEqualTo(1);
+	}
+
+	[Test]
+	public async Task SharedCache_AMovingPictureDoesNotChangeTheStillOne()
+	{
+		var cache = new MemoryPictureCache();
+		var registry = VtDecoding.Terminal.WithPictures(cache);
+		var still = registry.CreateDecoder();
+		var moving = registry.CreateDecoder();
+		var root = $"\e_Ga=t,i=3,f=32,s=1,v=1;{Convert.ToBase64String([0, 0, 0, 255])}\e\\";
+		still.Feed(root);
+		moving.Feed(root);
+		moving.Feed($"\e_Ga=f,i=3,f=32,s=1,v=1,X=1;{Convert.ToBase64String([255, 0, 0, 255])}\e\\");
+
+		var placed = (Decoder decoder) => decoder.Feed("\e_Ga=p,i=3,c=1,r=1\e\\\n")
+			.SelectMany(line => line.Content.Runs).SelectMany(run => run.Markups).OfType<ImageMarkup>().First();
+		await Assert.That(still.Pictures().TryGet(placed(still), out var a)).IsTrue();
+		await Assert.That(moving.Pictures().TryGet(placed(moving), out var b)).IsTrue();
+		await Assert.That(a!.IsMoving).IsFalse();
+		await Assert.That(b!.IsMoving).IsTrue();
+		await Assert.That(cache.Count).IsEqualTo(2);
+	}
+
+	private sealed class CountingCache : IPictureCache
+	{
+		public Dictionary<string, StoredPicture> Held { get; } = [];
+
+		public int Sets { get; private set; }
+
+		public bool TryGet(string key, [NotNullWhen(true)] out StoredPicture? picture) => Held.TryGetValue(key, out picture);
+
+		public void Set(StoredPicture picture)
+		{
+			Sets++;
+			Held[picture.Key] = picture;
+		}
+
+		public bool Remove(string key) => Held.Remove(key);
+	}
+
+	[Test]
+	public async Task CustomCache_HoldsThePictures()
+	{
+		var cache = new CountingCache();
+		var decoder = VtDecoding.Terminal.WithPictures(cache).CreateDecoder();
+		var lines = decoder.Feed(Wire(TerminalFeatures.InlineImages, RedBlue()));
+		var image = lines.SelectMany(line => line.Content.Runs).SelectMany(run => run.Markups).OfType<ImageMarkup>().First();
+		await Assert.That(cache.Held.ContainsKey(image.Source[PictureStore.Scheme.Length..])).IsTrue();
+		await Assert.That(cache.Sets).IsEqualTo(1);
 	}
 
 	[Test]
diff --git a/docs/decoding.md b/docs/decoding.md
index 356e4b1..da07b8e 100644
--- a/docs/decoding.md
+++ b/docs/decoding.md
@@ -489,13 +489,25 @@ foreach (var image in lines.SelectMany(l => l.Content.Runs).SelectMany(r => r.Ma
 The pixels live in the decoder's `PictureStore`, and an image's `Source` is `picture:` and a key
 (a hash of the picture, so the same picture sent twice is stored once). The store:
 
-- keeps `Budget` bytes (64 MiB), dropping the least recently used first. A line whose picture is gone
-  shows its text instead.
+- keeps its pictures in an `IPictureCache`: by default a `MemoryPictureCache` of its own, which holds
+  `Budget` bytes (64 MiB) and drops the least recently used first. A line whose picture is gone shows
+  its text instead.
+- shares one cache between connections with `WithPictures(cache)`, so a picture every player is sent
+  is decoded and kept once. A file already in the cache is not decoded again. The cache can be your
+  own (on disk, in Redis); it must be safe to call from several threads. A connection that adds
+  frames to a picture does so on a copy under a key of its own, so the still picture other lines
+  show does not change.
 - refuses a picture of more than `MaxPixels` (4096 × 4096).
 - is the `ITerminalPictureSource` to give `AnsiOutputOptions.Pictures`, so decoded pictures can be
   written to a terminal again.
 - gives `StoredPicture.ToDataUrl()` for an `<img>`, and raises `Added` so a host can serve pictures
-  from its own address instead.
+  from its own address instead. A picture already in a shared cache is not raised again.
+
+```csharp
+var cache = new MemoryPictureCache { Budget = 256L * 1024 * 1024 };   // one for the whole server
+var registry = DecoderRegistry.Empty.WithVt().WithPictures(cache);
+var decoder = registry.CreateDecoder();                               // per connection, same cache
+```
 
 PNG and sixel are decoded here, and Kitty's raw RGB and RGBA, zlib-compressed or not. A GIF, JPEG or
 WebP sent as an iTerm2 image is kept as the file with no pixels: a browser shows it, a terminal gets

From 65b7328d218b33e62e0d471c2211612c9c4e7748 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 23:16:14 +0000
Subject: [PATCH 17/19] Add injection seams and a dependency injection package

Core: IDecoderFactory (DecoderRegistry), IStyleResolver (DisplayRegistry; the
renderers take it), IUrlPolicy with UrlPolicy.Safe/WithSchemes as
DecoderOptions.Links and DisplayOptions.Links, and decode diagnostics reported
on the MarkupString.Decoding meter through an optional IMeterFactory.

MarkupString.Extensions.DependencyInjection: AddMarkupString() registers the
registries, a shared picture cache, a decoder factory, display defaults and
the link policy, configured in code or bound from configuration with the
source-generated binder. AOT smoke covers it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rqqt7WGskvSsoRXvKMqybx
---
 .github/workflows/ci.yml                      |   2 +-
 CHANGELOG.md                                  |   9 +
 Directory.Build.targets                       |   2 +-
 MarkupString.Ansi/Decoding/AnsiDisplay.cs     |   2 +-
 MarkupString.Ansi/Decoding/VtPlugins.cs       |   2 +-
 MarkupString.Ansi/UrlSafety.cs                |  12 +-
 .../MarkupString.AotSmoke.csproj              |   7 +
 MarkupString.AotSmoke/Program.cs              |  19 ++
 ...ring.Extensions.DependencyInjection.csproj |  30 +++
 .../MarkupStringOptions.cs                    |  63 ++++++
 .../PublicAPI.Shipped.txt                     |   1 +
 .../PublicAPI.Unshipped.txt                   |  50 +++++
 .../README.md                                 |  13 ++
 .../ServiceCollectionExtensions.cs            | 201 ++++++++++++++++++
 MarkupString.Mxp/Decoding/MxpDecoding.cs      |   2 +-
 .../Decoding/PuebloDecoding.cs                |   2 +-
 MarkupString.Tests/Decoding/InjectionTests.cs | 124 +++++++++++
 MarkupString.Tests/MarkupString.Tests.csproj  |   4 +
 MarkupString.slnx                             |   1 +
 MarkupString/Decoding/Decoder.cs              |  73 ++++++-
 MarkupString/Decoding/DecoderRegistry.cs      |  18 +-
 MarkupString/Display/CellRenderer.cs          |   2 +-
 MarkupString/Display/DisplayRegistry.cs       |   2 +-
 MarkupString/Display/DisplayStyle.cs          |  10 +
 MarkupString/Display/SpanRenderer.cs          |   2 +-
 MarkupString/PublicAPI.Unshipped.txt          |  21 +-
 MarkupString/UrlPolicy.cs                     |  47 ++++
 README.md                                     |   3 +
 docs/decoding.md                              |  10 +-
 docs/dependency-injection.md                  |  84 ++++++++
 docs/display.md                               |   4 +
 31 files changed, 790 insertions(+), 32 deletions(-)
 create mode 100644 MarkupString.Extensions.DependencyInjection/MarkupString.Extensions.DependencyInjection.csproj
 create mode 100644 MarkupString.Extensions.DependencyInjection/MarkupStringOptions.cs
 create mode 100644 MarkupString.Extensions.DependencyInjection/PublicAPI.Shipped.txt
 create mode 100644 MarkupString.Extensions.DependencyInjection/PublicAPI.Unshipped.txt
 create mode 100644 MarkupString.Extensions.DependencyInjection/README.md
 create mode 100644 MarkupString.Extensions.DependencyInjection/ServiceCollectionExtensions.cs
 create mode 100644 MarkupString.Tests/Decoding/InjectionTests.cs
 create mode 100644 MarkupString/UrlPolicy.cs
 create mode 100644 docs/dependency-injection.md

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b2943e2..715f6a1 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -23,7 +23,7 @@ jobs:
       # SDK (the MSBuild build host crashes). Whitespace rules are syntactic, so nothing is lost.
       - name: Verify formatting
         run: |
-          for dir in MarkupString MarkupString.Ansi MarkupString.Html MarkupString.Mxp MarkupString.Pueblo MarkupString.Tests MarkupString.AotSmoke; do
+          for dir in MarkupString MarkupString.Ansi MarkupString.Extensions.DependencyInjection MarkupString.Html MarkupString.Mxp MarkupString.Pueblo MarkupString.Tests MarkupString.AotSmoke; do
             dotnet format whitespace --folder "$dir" --exclude "**/bin/**" --exclude "**/obj/**" --verify-no-changes
           done
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4778ffd..f4aae04 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,6 +33,15 @@ follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   models. See [Display](docs/display.md).
 - `CommandMenuMarkup` (a menu of commands, or a prompt), `HighlightMarkup` (a background) and `LinkGroupMarkup`
   (an OSC 8 `id`, which becomes `Interaction.Group`) in core, with codecs.
+- **`MarkupString.Extensions.DependencyInjection`**: `AddMarkupString()` registers the markup, decoder and display
+  registries, a shared picture cache, an `IDecoderFactory`, default `DisplayOptions` and the link policy as singletons,
+  configured in code or with `BindConfiguration()` (`MarkupStringOptions`, AOT-safe). See
+  [Dependency injection](docs/dependency-injection.md).
+- Interfaces to inject: `IDecoderFactory` (a `DecoderRegistry` is one), `IStyleResolver` (a `DisplayRegistry` is one;
+  `SpanRenderer` and `CellRenderer` take it), and `IUrlPolicy` with `UrlPolicy.Safe` and `UrlPolicy.WithSchemes`, set as
+  `DecoderOptions.Links` and `DisplayOptions.Links`.
+- Decode diagnostics are reported on the `MarkupString.Decoding` meter (`markupstring.decoding.dropped`, by `kind`),
+  through `DecoderOptions.Meters` when a host gives its `IMeterFactory`.
 - `IPictureCache` and `MemoryPictureCache`: `WithPictures(cache)` shares decoded pictures between connections, and a
   host can keep them in a cache of its own.
 - Kitty animation frames (`a=f`, and frame times with `a=a`) decode into a moving `StoredPicture`, given as a GIF.
diff --git a/Directory.Build.targets b/Directory.Build.targets
index 4654d8e..201a538 100644
--- a/Directory.Build.targets
+++ b/Directory.Build.targets
@@ -1,7 +1,7 @@
 <Project>
 
   <!-- Keep the package family recognizable with one embedded NuGet icon. -->
-  <PropertyGroup Condition="'$(PackageId)' == 'MarkupString' OR '$(PackageId)' == 'MarkupString.Ansi' OR '$(PackageId)' == 'MarkupString.Html' OR '$(PackageId)' == 'MarkupString.Mxp' OR '$(PackageId)' == 'MarkupString.Pueblo'">
+  <PropertyGroup Condition="'$(PackageId)' == 'MarkupString' OR '$(PackageId)' == 'MarkupString.Ansi' OR '$(PackageId)' == 'MarkupString.Html' OR '$(PackageId)' == 'MarkupString.Mxp' OR '$(PackageId)' == 'MarkupString.Pueblo' OR '$(PackageId)' == 'MarkupString.Extensions.DependencyInjection'">
     <PackageIcon>markupstring-icon.png</PackageIcon>
   </PropertyGroup>
   <ItemGroup Condition="'$(PackageIcon)' == 'markupstring-icon.png'">
diff --git a/MarkupString.Ansi/Decoding/AnsiDisplay.cs b/MarkupString.Ansi/Decoding/AnsiDisplay.cs
index 9c73f16..093e54b 100644
--- a/MarkupString.Ansi/Decoding/AnsiDisplay.cs
+++ b/MarkupString.Ansi/Decoding/AnsiDisplay.cs
@@ -142,7 +142,7 @@ public void Contribute(MarkupSet markups, StyleBuilder style, DisplayOptions opt
 			{
 				style.Interaction = new Interaction(InteractionKind.Command, folded.LinkUrl) { Hint = folded.LinkText };
 			}
-			else if (UrlSafety.IsSafeNavigableUrl(folded.LinkUrl))
+			else if (options.Links.IsAllowed(folded.LinkUrl))
 			{
 				style.Interaction = new Interaction(InteractionKind.Url, folded.LinkUrl) { Hint = folded.LinkText };
 			}
diff --git a/MarkupString.Ansi/Decoding/VtPlugins.cs b/MarkupString.Ansi/Decoding/VtPlugins.cs
index 6b7600f..63196a4 100644
--- a/MarkupString.Ansi/Decoding/VtPlugins.cs
+++ b/MarkupString.Ansi/Decoding/VtPlugins.cs
@@ -394,7 +394,7 @@ public void Register(DecoderBuilder builder)
 				}
 
 				var target = uri.ToString();
-				var safe = UrlSafety.IsSafeNavigableUrl(target);
+				var safe = context.Options.Links.IsAllowed(target);
 				context.SetPen(VtPens.Link, safe ? new AnsiMarkup(new AnsiStyle { LinkUrl = target, LinkKind = LinkKind.Url }) : null);
 				var id = safe ? LinkId(payload[..separator]) : null;
 				context.SetPen(VtPens.LinkGroup, id is null ? null : new LinkGroupMarkup(id));
diff --git a/MarkupString.Ansi/UrlSafety.cs b/MarkupString.Ansi/UrlSafety.cs
index 245470b..c17ee4e 100644
--- a/MarkupString.Ansi/UrlSafety.cs
+++ b/MarkupString.Ansi/UrlSafety.cs
@@ -10,15 +10,5 @@ public static class UrlSafety
 	/// carrying one renders as plain text instead. This applies to URL links only — a command link
 	/// carries a MUSH command, never a browser-navigable href.
 	/// </summary>
-	public static bool IsSafeNavigableUrl(string? url)
-	{
-		if (string.IsNullOrWhiteSpace(url)) return false;
-		if (!Uri.TryCreate(url, UriKind.RelativeOrAbsolute, out var uri)) return false;
-
-		// A relative URL or a bare fragment cannot name a scheme, so there is none to distrust.
-		if (!uri.IsAbsoluteUri) return true;
-
-		// Uri.Scheme is already lower-cased, so "JavaScript:" is caught here too.
-		return uri.Scheme is "http" or "https" or "mailto" or "ftp" or "ftps" or "tel";
-	}
+	public static bool IsSafeNavigableUrl(string? url) => url is not null && UrlPolicy.Safe.IsAllowed(url);
 }
diff --git a/MarkupString.AotSmoke/MarkupString.AotSmoke.csproj b/MarkupString.AotSmoke/MarkupString.AotSmoke.csproj
index 820fcfb..0306f65 100644
--- a/MarkupString.AotSmoke/MarkupString.AotSmoke.csproj
+++ b/MarkupString.AotSmoke/MarkupString.AotSmoke.csproj
@@ -17,14 +17,21 @@
   <ItemGroup>
     <TrimmerRootAssembly Include="MarkupString" />
     <TrimmerRootAssembly Include="MarkupString.Ansi" />
+    <TrimmerRootAssembly Include="MarkupString.Extensions.DependencyInjection" />
     <TrimmerRootAssembly Include="MarkupString.Html" />
     <TrimmerRootAssembly Include="MarkupString.Mxp" />
     <TrimmerRootAssembly Include="MarkupString.Pueblo" />
   </ItemGroup>
 
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
+  </ItemGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\MarkupString\MarkupString.csproj" />
     <ProjectReference Include="..\MarkupString.Ansi\MarkupString.Ansi.csproj" />
+    <ProjectReference Include="..\MarkupString.Extensions.DependencyInjection\MarkupString.Extensions.DependencyInjection.csproj" />
     <ProjectReference Include="..\MarkupString.Html\MarkupString.Html.csproj" />
     <ProjectReference Include="..\MarkupString.Mxp\MarkupString.Mxp.csproj" />
     <ProjectReference Include="..\MarkupString.Pueblo\MarkupString.Pueblo.csproj" />
diff --git a/MarkupString.AotSmoke/Program.cs b/MarkupString.AotSmoke/Program.cs
index 736e4d4..56c92aa 100644
--- a/MarkupString.AotSmoke/Program.cs
+++ b/MarkupString.AotSmoke/Program.cs
@@ -4,12 +4,15 @@
 using MarkupString.Ansi.Decoding;
 using MarkupString.Decoding;
 using MarkupString.Display;
+using MarkupString.Extensions.DependencyInjection;
 using MarkupString.Html;
 using MarkupString.Layout;
 using MarkupString.Mxp;
 using MarkupString.Mxp.Decoding;
 using MarkupString.Pueblo;
 using MarkupString.Pueblo.Decoding;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
 
 // Native-AOT smoke test. It is published with PublishAot and run in CI: the publish must produce no
 // IL2xxx/IL3xxx warning, and the binary must exit 0. What it exercises is the whole pipeline that a
@@ -149,6 +152,22 @@
 	|| CellRenderer.Layout(decoded[2].Content, 80, AnsiDisplay.Default, new DisplayOptions()).Rows[0].Cells[0].Style.Picture is null)
 	failures.Add("decoding a sixel picture failed");
 
+// Dependency injection, with options bound from configuration by the source-generated binder.
+var configuration = new ConfigurationBuilder().AddInMemoryCollection(new Dictionary<string, string?>
+{
+	["MarkupString:LinkSchemes:0"] = "mudclient",
+	["MarkupString:Display:Colors"] = "Standard",
+}).Build();
+using (var services = new ServiceCollection().AddSingleton<IConfiguration>(configuration)
+	.AddMarkupString().BindConfiguration().AddDecoders(registry => registry.WithMxp()).Services.BuildServiceProvider())
+{
+	var injected = services.GetRequiredService<IDecoderFactory>().CreateDecoder();
+	var linked = injected.Feed("\e]8;;mudclient://look\e\\look\e]8;;\e\\\n");
+	var shown = SpanRenderer.Render(linked[0].Content, services.GetRequiredService<IStyleResolver>(), services.GetRequiredService<DisplayOptions>());
+	if (shown[0].Style.Interaction?.Target != "mudclient://look" || services.GetRequiredService<DisplayOptions>().Capabilities.Colors != ColorLevel.Standard)
+		failures.Add("dependency injection failed");
+}
+
 if (failures.Count > 0)
 {
 	Console.Error.WriteLine("AOT smoke test failed:");
diff --git a/MarkupString.Extensions.DependencyInjection/MarkupString.Extensions.DependencyInjection.csproj b/MarkupString.Extensions.DependencyInjection/MarkupString.Extensions.DependencyInjection.csproj
new file mode 100644
index 0000000..4e89dae
--- /dev/null
+++ b/MarkupString.Extensions.DependencyInjection/MarkupString.Extensions.DependencyInjection.csproj
@@ -0,0 +1,30 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <AssemblyName>MarkupString.Extensions.DependencyInjection</AssemblyName>
+    <RootNamespace>MarkupString.Extensions.DependencyInjection</RootNamespace>
+    <PackageId>MarkupString.Extensions.DependencyInjection</PackageId>
+    <Title>MarkupString.Extensions.DependencyInjection</Title>
+    <IsAotCompatible>true</IsAotCompatible>
+    <EnableConfigurationBindingGenerator>true</EnableConfigurationBindingGenerator>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>CS1591</NoWarn>
+    <Description>Microsoft.Extensions.DependencyInjection setup for MarkupString: AddMarkupString() registers the markup, decoder and display registries, a shared picture cache, a decoder factory and the link policy, configured in code or bound from configuration.</Description>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="MinVer" Version="8.0.0" PrivateAssets="all" />
+    <PackageReference Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="5.6.0" PrivateAssets="all" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Options" Version="10.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="10.0.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="README.md" Pack="true" PackagePath="/" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\MarkupString\MarkupString.csproj" />
+    <ProjectReference Include="..\MarkupString.Ansi\MarkupString.Ansi.csproj" />
+  </ItemGroup>
+</Project>
diff --git a/MarkupString.Extensions.DependencyInjection/MarkupStringOptions.cs b/MarkupString.Extensions.DependencyInjection/MarkupStringOptions.cs
new file mode 100644
index 0000000..b00b6c3
--- /dev/null
+++ b/MarkupString.Extensions.DependencyInjection/MarkupStringOptions.cs
@@ -0,0 +1,63 @@
+using MarkupString.Display;
+namespace MarkupString.Extensions.DependencyInjection;
+
+/// <summary>
+/// The settings <see cref="ServiceCollectionExtensions.AddMarkupString"/> reads: set in code, or bound from a
+/// configuration section (<c>"MarkupString"</c> in <c>appsettings.json</c>).
+/// </summary>
+public sealed class MarkupStringOptions
+{
+	/// <summary>How each connection's output is read.</summary>
+	public DecodingSettings Decoding { get; set; } = new();
+
+	/// <summary>How pictures are kept.</summary>
+	public PictureSettings Pictures { get; set; } = new();
+
+	/// <summary>How styles are drawn.</summary>
+	public DisplaySettings Display { get; set; } = new();
+
+	/// <summary>
+	/// Link schemes allowed besides <c>http</c>, <c>https</c>, <c>mailto</c>, <c>ftp</c>, <c>ftps</c> and <c>tel</c>,
+	/// such as <c>mudclient</c>. <c>javascript</c>, <c>data</c>, <c>vbscript</c> and <c>file</c> are never allowed.
+	/// </summary>
+	public List<string> LinkSchemes { get; set; } = [];
+}
+
+/// <summary>How each connection's output is read.</summary>
+public sealed class DecodingSettings
+{
+	/// <summary>The longest line, in characters.</summary>
+	public int MaxLineLength { get; set; } = 64 * 1024;
+
+	/// <summary>The most elements a text protocol may have open at once.</summary>
+	public int MaxOpenElements { get; set; } = 64;
+
+	/// <summary>Whether a server may be told the cursor position (<c>CSI 6 n</c>).</summary>
+	public bool AnswerCursorPosition { get; set; }
+}
+
+/// <summary>How pictures are kept.</summary>
+public sealed class PictureSettings
+{
+	/// <summary>Whether pictures are read at all.</summary>
+	public bool Enabled { get; set; } = true;
+
+	/// <summary>The bytes the shared <see cref="Ansi.Decoding.MemoryPictureCache"/> holds. 64 MiB unless set.</summary>
+	public long Budget { get; set; } = 64L * 1024 * 1024;
+
+	/// <summary>The largest picture decoded, in pixels.</summary>
+	public long MaxPixels { get; set; } = 4096L * 4096;
+}
+
+/// <summary>How styles are drawn.</summary>
+public sealed class DisplaySettings
+{
+	/// <summary>The output drawn for unless a caller says otherwise: <c>Browser</c>, <c>CellGrid</c> or <c>PlainText</c>.</summary>
+	public string Output { get; set; } = "Browser";
+
+	/// <summary>The most colours shown, or null for what <see cref="Output"/> shows.</summary>
+	public ColorLevel? Colors { get; set; }
+
+	/// <summary>Whether bold standard colours are drawn bright, as many MU* clients do.</summary>
+	public bool BoldIsBright { get; set; }
+}
diff --git a/MarkupString.Extensions.DependencyInjection/PublicAPI.Shipped.txt b/MarkupString.Extensions.DependencyInjection/PublicAPI.Shipped.txt
new file mode 100644
index 0000000..7dc5c58
--- /dev/null
+++ b/MarkupString.Extensions.DependencyInjection/PublicAPI.Shipped.txt
@@ -0,0 +1 @@
+#nullable enable
diff --git a/MarkupString.Extensions.DependencyInjection/PublicAPI.Unshipped.txt b/MarkupString.Extensions.DependencyInjection/PublicAPI.Unshipped.txt
new file mode 100644
index 0000000..53f1e13
--- /dev/null
+++ b/MarkupString.Extensions.DependencyInjection/PublicAPI.Unshipped.txt
@@ -0,0 +1,50 @@
+#nullable enable
+MarkupString.Extensions.DependencyInjection.DecodingSettings
+MarkupString.Extensions.DependencyInjection.DecodingSettings.AnswerCursorPosition.get -> bool
+MarkupString.Extensions.DependencyInjection.DecodingSettings.AnswerCursorPosition.set -> void
+MarkupString.Extensions.DependencyInjection.DecodingSettings.DecodingSettings() -> void
+MarkupString.Extensions.DependencyInjection.DecodingSettings.MaxLineLength.get -> int
+MarkupString.Extensions.DependencyInjection.DecodingSettings.MaxLineLength.set -> void
+MarkupString.Extensions.DependencyInjection.DecodingSettings.MaxOpenElements.get -> int
+MarkupString.Extensions.DependencyInjection.DecodingSettings.MaxOpenElements.set -> void
+MarkupString.Extensions.DependencyInjection.DisplaySettings
+MarkupString.Extensions.DependencyInjection.DisplaySettings.BoldIsBright.get -> bool
+MarkupString.Extensions.DependencyInjection.DisplaySettings.BoldIsBright.set -> void
+MarkupString.Extensions.DependencyInjection.DisplaySettings.Colors.get -> MarkupString.Display.ColorLevel?
+MarkupString.Extensions.DependencyInjection.DisplaySettings.Colors.set -> void
+MarkupString.Extensions.DependencyInjection.DisplaySettings.DisplaySettings() -> void
+MarkupString.Extensions.DependencyInjection.DisplaySettings.Output.get -> string!
+MarkupString.Extensions.DependencyInjection.DisplaySettings.Output.set -> void
+MarkupString.Extensions.DependencyInjection.MarkupDecoderFactory
+MarkupString.Extensions.DependencyInjection.MarkupDecoderFactory.CreateDecoder(MarkupString.Decoding.DecoderOptions? options = null) -> MarkupString.Decoding.Decoder!
+MarkupString.Extensions.DependencyInjection.MarkupDecoderFactory.Defaults.get -> MarkupString.Decoding.DecoderOptions!
+MarkupString.Extensions.DependencyInjection.MarkupDecoderFactory.MarkupDecoderFactory(MarkupString.Decoding.DecoderRegistry! registry, MarkupString.Extensions.DependencyInjection.MarkupStringOptions! options, MarkupString.IUrlPolicy! links, System.Diagnostics.Metrics.IMeterFactory? meters = null) -> void
+MarkupString.Extensions.DependencyInjection.MarkupStringBuilder
+MarkupString.Extensions.DependencyInjection.MarkupStringBuilder.AddDecoders(System.Func<MarkupString.Decoding.DecoderRegistry!, MarkupString.Decoding.DecoderRegistry!>! configure) -> MarkupString.Extensions.DependencyInjection.MarkupStringBuilder!
+MarkupString.Extensions.DependencyInjection.MarkupStringBuilder.AddDisplay(System.Func<MarkupString.Display.DisplayRegistry!, MarkupString.Display.DisplayRegistry!>! configure) -> MarkupString.Extensions.DependencyInjection.MarkupStringBuilder!
+MarkupString.Extensions.DependencyInjection.MarkupStringBuilder.AddMarkup(System.Func<MarkupString.MarkupRegistry!, MarkupString.MarkupRegistry!>! configure) -> MarkupString.Extensions.DependencyInjection.MarkupStringBuilder!
+MarkupString.Extensions.DependencyInjection.MarkupStringBuilder.BindConfiguration(string! path = "MarkupString") -> MarkupString.Extensions.DependencyInjection.MarkupStringBuilder!
+MarkupString.Extensions.DependencyInjection.MarkupStringBuilder.Services.get -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
+MarkupString.Extensions.DependencyInjection.MarkupStringBuilder.UsePictureCache<TCache>() -> MarkupString.Extensions.DependencyInjection.MarkupStringBuilder!
+MarkupString.Extensions.DependencyInjection.MarkupStringBuilder.UseUrlPolicy<TPolicy>() -> MarkupString.Extensions.DependencyInjection.MarkupStringBuilder!
+MarkupString.Extensions.DependencyInjection.MarkupStringOptions
+MarkupString.Extensions.DependencyInjection.MarkupStringOptions.Decoding.get -> MarkupString.Extensions.DependencyInjection.DecodingSettings!
+MarkupString.Extensions.DependencyInjection.MarkupStringOptions.Decoding.set -> void
+MarkupString.Extensions.DependencyInjection.MarkupStringOptions.Display.get -> MarkupString.Extensions.DependencyInjection.DisplaySettings!
+MarkupString.Extensions.DependencyInjection.MarkupStringOptions.Display.set -> void
+MarkupString.Extensions.DependencyInjection.MarkupStringOptions.LinkSchemes.get -> System.Collections.Generic.List<string!>!
+MarkupString.Extensions.DependencyInjection.MarkupStringOptions.LinkSchemes.set -> void
+MarkupString.Extensions.DependencyInjection.MarkupStringOptions.MarkupStringOptions() -> void
+MarkupString.Extensions.DependencyInjection.MarkupStringOptions.Pictures.get -> MarkupString.Extensions.DependencyInjection.PictureSettings!
+MarkupString.Extensions.DependencyInjection.MarkupStringOptions.Pictures.set -> void
+MarkupString.Extensions.DependencyInjection.PictureSettings
+MarkupString.Extensions.DependencyInjection.PictureSettings.Budget.get -> long
+MarkupString.Extensions.DependencyInjection.PictureSettings.Budget.set -> void
+MarkupString.Extensions.DependencyInjection.PictureSettings.Enabled.get -> bool
+MarkupString.Extensions.DependencyInjection.PictureSettings.Enabled.set -> void
+MarkupString.Extensions.DependencyInjection.PictureSettings.MaxPixels.get -> long
+MarkupString.Extensions.DependencyInjection.PictureSettings.MaxPixels.set -> void
+MarkupString.Extensions.DependencyInjection.PictureSettings.PictureSettings() -> void
+MarkupString.Extensions.DependencyInjection.ServiceCollectionExtensions
+static MarkupString.Extensions.DependencyInjection.ServiceCollectionExtensions.AddMarkupString(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, System.Action<MarkupString.Extensions.DependencyInjection.MarkupStringOptions!>? configure = null) -> MarkupString.Extensions.DependencyInjection.MarkupStringBuilder!
+MarkupString.Extensions.DependencyInjection.MarkupDecoderFactory.CreateDecoderFor(MarkupString.Decoding.ClientIdentity! identity) -> MarkupString.Decoding.Decoder!
diff --git a/MarkupString.Extensions.DependencyInjection/README.md b/MarkupString.Extensions.DependencyInjection/README.md
new file mode 100644
index 0000000..4fd6ae5
--- /dev/null
+++ b/MarkupString.Extensions.DependencyInjection/README.md
@@ -0,0 +1,13 @@
+# MarkupString.Extensions.DependencyInjection
+
+`AddMarkupString()` for `Microsoft.Extensions.DependencyInjection` hosts such as ASP.NET Core. See
+[Dependency injection](https://github.com/SharpMUSH/MarkupString/blob/main/docs/dependency-injection.md).
+
+```csharp
+builder.Services.AddMarkupString()
+    .BindConfiguration()                                  // "MarkupString" in appsettings.json
+    .AddDecoders(registry => registry.WithMxp().WithPueblo());
+
+// per connection
+var decoder = app.Services.GetRequiredService<IDecoderFactory>().CreateDecoder();
+```
diff --git a/MarkupString.Extensions.DependencyInjection/ServiceCollectionExtensions.cs b/MarkupString.Extensions.DependencyInjection/ServiceCollectionExtensions.cs
new file mode 100644
index 0000000..0d3294d
--- /dev/null
+++ b/MarkupString.Extensions.DependencyInjection/ServiceCollectionExtensions.cs
@@ -0,0 +1,201 @@
+using System.Diagnostics.CodeAnalysis;
+using System.Diagnostics.Metrics;
+using MarkupString.Ansi;
+using MarkupString.Ansi.Decoding;
+using MarkupString.Decoding;
+using MarkupString.Display;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using Microsoft.Extensions.Options;
+namespace MarkupString.Extensions.DependencyInjection;
+
+/// <summary>Registers MarkupString with a service collection.</summary>
+public static class ServiceCollectionExtensions
+{
+	/// <summary>
+	/// Registers, as singletons: the <see cref="MarkupRegistry"/>; the <see cref="DecoderRegistry"/> (VT and
+	/// pictures) and an <see cref="IDecoderFactory"/> that makes each connection's decoder with the configured limits;
+	/// one <see cref="IPictureCache"/> every connection shares; the <see cref="DisplayRegistry"/> as the
+	/// <see cref="IStyleResolver"/>, with default <see cref="DisplayOptions"/>; and the <see cref="IUrlPolicy"/>.
+	/// Decode metrics go to the host's <see cref="IMeterFactory"/> when it has one. A service registered before this
+	/// call is kept, so any of them can be replaced. Calling it again adds to the same setup.
+	/// </summary>
+	public static MarkupStringBuilder AddMarkupString(this IServiceCollection services, Action<MarkupStringOptions>? configure = null)
+	{
+		ArgumentNullException.ThrowIfNull(services);
+		var setup = Setup(services);
+		services.AddOptions<MarkupStringOptions>();
+		if (configure is not null) services.Configure(configure);
+
+		services.TryAddSingleton<IUrlPolicy>(static sp => UrlPolicy.WithSchemes(Options(sp).LinkSchemes));
+		services.TryAddSingleton<IPictureCache>(static sp => new MemoryPictureCache { Budget = Options(sp).Pictures.Budget });
+		services.TryAddSingleton(sp =>
+		{
+			var options = Options(sp);
+			var registry = DecoderRegistry.Empty.WithVt();
+			if (options.Pictures.Enabled) registry = registry.WithPictures(sp.GetRequiredService<IPictureCache>());
+			return setup.Decoders.Aggregate(registry, static (current, step) => step(current));
+		});
+		services.TryAddSingleton(static sp => new MarkupDecoderFactory(
+			sp.GetRequiredService<DecoderRegistry>(),
+			Options(sp),
+			sp.GetRequiredService<IUrlPolicy>(),
+			sp.GetService<IMeterFactory>()));
+		services.TryAddSingleton<IDecoderFactory>(static sp => sp.GetRequiredService<MarkupDecoderFactory>());
+		services.TryAddSingleton(sp => setup.Display.Aggregate(
+			DisplayRegistry.Core.WithAnsi(Options(sp).Display.BoldIsBright), static (current, step) => step(current)));
+		services.TryAddSingleton<IStyleResolver>(static sp => sp.GetRequiredService<DisplayRegistry>());
+		services.TryAddSingleton(static sp => DisplayDefaults(Options(sp).Display, sp.GetRequiredService<IUrlPolicy>()));
+		services.TryAddSingleton(sp => setup.Markup.Aggregate(MarkupRegistry.Empty.WithAnsi(), static (current, step) => step(current)));
+		return new MarkupStringBuilder(services, setup);
+	}
+
+	private static MarkupStringOptions Options(IServiceProvider services) => services.GetRequiredService<IOptions<MarkupStringOptions>>().Value;
+
+	private static DisplayOptions DisplayDefaults(DisplaySettings settings, IUrlPolicy links)
+	{
+		var capabilities = settings.Output.ToUpperInvariant() switch
+		{
+			"CELLGRID" => OutputCapabilities.CellGrid,
+			"PLAINTEXT" => OutputCapabilities.PlainText,
+			"BROWSER" => OutputCapabilities.Browser,
+			_ => throw new OptionsValidationException(nameof(DisplaySettings.Output), typeof(MarkupStringOptions),
+				[$"MarkupString:Display:Output is '{settings.Output}'; it must be Browser, CellGrid or PlainText."]),
+		};
+		if (settings.Colors is { } colors) capabilities = capabilities with { Colors = colors };
+		return new DisplayOptions { Capabilities = capabilities, Links = links };
+	}
+
+	private static MarkupStringSetup Setup(IServiceCollection services)
+	{
+		foreach (var descriptor in services)
+		{
+			if (descriptor.ServiceType == typeof(MarkupStringSetup) && descriptor.ImplementationInstance is MarkupStringSetup existing) return existing;
+		}
+
+		var setup = new MarkupStringSetup();
+		services.AddSingleton(setup);
+		return setup;
+	}
+}
+
+/// <summary>The steps <see cref="MarkupStringBuilder"/> collects, applied when the registries are first resolved.</summary>
+internal sealed class MarkupStringSetup
+{
+	public List<Func<DecoderRegistry, DecoderRegistry>> Decoders { get; } = [];
+
+	public List<Func<DisplayRegistry, DisplayRegistry>> Display { get; } = [];
+
+	public List<Func<MarkupRegistry, MarkupRegistry>> Markup { get; } = [];
+}
+
+/// <summary>Adds to what <see cref="ServiceCollectionExtensions.AddMarkupString"/> registered.</summary>
+public sealed class MarkupStringBuilder
+{
+	private readonly MarkupStringSetup _setup;
+
+	internal MarkupStringBuilder(IServiceCollection services, MarkupStringSetup setup)
+	{
+		Services = services;
+		_setup = setup;
+	}
+
+	/// <summary>The service collection.</summary>
+	public IServiceCollection Services { get; }
+
+	/// <summary>Adds decoder plugins, such as <c>registry =&gt; registry.WithMxp().WithPueblo()</c>.</summary>
+	public MarkupStringBuilder AddDecoders(Func<DecoderRegistry, DecoderRegistry> configure)
+	{
+		ArgumentNullException.ThrowIfNull(configure);
+		_setup.Decoders.Add(configure);
+		return this;
+	}
+
+	/// <summary>Adds style contributors to the display registry.</summary>
+	public MarkupStringBuilder AddDisplay(Func<DisplayRegistry, DisplayRegistry> configure)
+	{
+		ArgumentNullException.ThrowIfNull(configure);
+		_setup.Display.Add(configure);
+		return this;
+	}
+
+	/// <summary>Adds emitters and codecs to the markup registry, such as <c>registry =&gt; registry.WithHtml()</c>.</summary>
+	public MarkupStringBuilder AddMarkup(Func<MarkupRegistry, MarkupRegistry> configure)
+	{
+		ArgumentNullException.ThrowIfNull(configure);
+		_setup.Markup.Add(configure);
+		return this;
+	}
+
+	/// <summary>Binds <see cref="MarkupStringOptions"/> to the configuration section at <paramref name="path"/>.</summary>
+	public MarkupStringBuilder BindConfiguration(string path = "MarkupString")
+	{
+		ArgumentException.ThrowIfNullOrEmpty(path);
+		Services.AddOptions<MarkupStringOptions>().BindConfiguration(path);
+		return this;
+	}
+
+	/// <summary>Keeps pictures in <typeparamref name="TCache"/>, a singleton, instead of memory.</summary>
+	public MarkupStringBuilder UsePictureCache<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] TCache>()
+		where TCache : class, IPictureCache
+	{
+		Services.Replace(ServiceDescriptor.Singleton<IPictureCache, TCache>());
+		return this;
+	}
+
+	/// <summary>Decides which links are allowed with <typeparamref name="TPolicy"/>, a singleton.</summary>
+	public MarkupStringBuilder UseUrlPolicy<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] TPolicy>()
+		where TPolicy : class, IUrlPolicy
+	{
+		Services.Replace(ServiceDescriptor.Singleton<IUrlPolicy, TPolicy>());
+		return this;
+	}
+}
+
+/// <summary>
+/// Makes each connection's <see cref="Decoder"/> from the registered <see cref="DecoderRegistry"/>, with the
+/// configured limits, link policy, metrics and picture size.
+/// </summary>
+public sealed class MarkupDecoderFactory : IDecoderFactory
+{
+	private readonly DecoderRegistry _registry;
+	private readonly long _maxPixels;
+
+	/// <summary>A factory over <paramref name="registry"/>.</summary>
+	public MarkupDecoderFactory(DecoderRegistry registry, MarkupStringOptions options, IUrlPolicy links, IMeterFactory? meters = null)
+	{
+		ArgumentNullException.ThrowIfNull(registry);
+		ArgumentNullException.ThrowIfNull(options);
+		ArgumentNullException.ThrowIfNull(links);
+		_registry = registry;
+		_maxPixels = options.Pictures.MaxPixels;
+		var answers = ClientAnswers.Default;
+		answers = options.Decoding.AnswerCursorPosition ? answers | ClientAnswers.CursorPosition : answers & ~ClientAnswers.CursorPosition;
+		Defaults = new DecoderOptions
+		{
+			MaxLineLength = options.Decoding.MaxLineLength,
+			MaxOpenElements = options.Decoding.MaxOpenElements,
+			Links = links,
+			Meters = meters,
+			Identity = new ClientIdentity { Answers = answers },
+		};
+	}
+
+	/// <summary>What each decoder is made with unless a caller gives its own.</summary>
+	public DecoderOptions Defaults { get; }
+
+	/// <inheritdoc/>
+	public Decoder CreateDecoder(DecoderOptions? options = null)
+	{
+		var decoder = _registry.CreateDecoder(options ?? Defaults);
+		if (_registry.Has(PicturesPlugin.Instance.Name)) decoder.Pictures().MaxPixels = _maxPixels;
+		return decoder;
+	}
+
+	/// <summary>A decoder with the defaults, for a client that is <paramref name="identity"/>.</summary>
+	public Decoder CreateDecoderFor(ClientIdentity identity)
+	{
+		ArgumentNullException.ThrowIfNull(identity);
+		return CreateDecoder(Defaults with { Identity = identity });
+	}
+}
diff --git a/MarkupString.Mxp/Decoding/MxpDecoding.cs b/MarkupString.Mxp/Decoding/MxpDecoding.cs
index a38e74a..04dc49b 100644
--- a/MarkupString.Mxp/Decoding/MxpDecoding.cs
+++ b/MarkupString.Mxp/Decoding/MxpDecoding.cs
@@ -384,7 +384,7 @@ private bool Element(ParsedTag tag, bool openMode)
 			case "A":
 				{
 					var href = tag.Get("HREF", 0);
-					IMarkup? link = href is not null && UrlSafety.IsSafeNavigableUrl(href)
+					IMarkup? link = href is not null && Context.Options.Links.IsAllowed(href)
 						? new AnsiMarkup(new AnsiStyle { LinkUrl = href, LinkKind = LinkKind.Url, LinkText = tag.Get("HINT", 1) })
 						: null;
 					OpenElement(tag.Name, link is null ? [] : [link], openMode);
diff --git a/MarkupString.Pueblo/Decoding/PuebloDecoding.cs b/MarkupString.Pueblo/Decoding/PuebloDecoding.cs
index e8e75b1..dec48d6 100644
--- a/MarkupString.Pueblo/Decoding/PuebloDecoding.cs
+++ b/MarkupString.Pueblo/Decoding/PuebloDecoding.cs
@@ -198,7 +198,7 @@ private bool Element(ParsedTag tag, string name)
 					{
 						link = new AnsiStyle { LinkUrl = command, LinkKind = LinkKind.Command, LinkText = hint };
 					}
-					else if (tag.Get("href") is { } href && UrlSafety.IsSafeNavigableUrl(href))
+					else if (tag.Get("href") is { } href && Context.Options.Links.IsAllowed(href))
 					{
 						link = new AnsiStyle { LinkUrl = href, LinkKind = LinkKind.Url, LinkText = hint };
 					}
diff --git a/MarkupString.Tests/Decoding/InjectionTests.cs b/MarkupString.Tests/Decoding/InjectionTests.cs
new file mode 100644
index 0000000..13a0f4e
--- /dev/null
+++ b/MarkupString.Tests/Decoding/InjectionTests.cs
@@ -0,0 +1,124 @@
+using System.Diagnostics.CodeAnalysis;
+using System.Diagnostics.Metrics;
+using MarkupString.Ansi.Decoding;
+using MarkupString.Decoding;
+using MarkupString.Display;
+using MarkupString.Extensions.DependencyInjection;
+using MarkupString.Mxp.Decoding;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+
+/// <summary>The seams a host injects through, and the package that wires them into a service collection.</summary>
+public class InjectionTests
+{
+	private const string MudLink = "\e]8;;mudclient://look\e\\look\e]8;;\e\\\n";
+
+	private static Interaction? FirstInteraction(IReadOnlyList<DisplayLine> lines, IStyleResolver styles, DisplayOptions options) =>
+		SpanRenderer.Render(lines[0].Content, styles, options)[0].Style.Interaction;
+
+	[Test]
+	public async Task UrlPolicy_AddsSchemes_ButNeverTheDangerousOnes()
+	{
+		var policy = UrlPolicy.WithSchemes("mudclient", "JavaScript");
+		await Assert.That(policy.IsAllowed("mudclient://look")).IsTrue();
+		await Assert.That(policy.IsAllowed("javascript:alert(1)")).IsFalse();
+		await Assert.That(policy.IsAllowed("/relative")).IsTrue();
+		await Assert.That(UrlPolicy.Safe.IsAllowed("mudclient://look")).IsFalse();
+	}
+
+	[Test]
+	public async Task UrlPolicy_DecidesDecodedAndDisplayedLinks()
+	{
+		var policy = UrlPolicy.WithSchemes("mudclient");
+		var lines = VtDecoding.Terminal.CreateDecoder(new DecoderOptions { Links = policy }).Feed(MudLink);
+		var display = new DisplayOptions { Links = policy };
+		await Assert.That(FirstInteraction(lines, AnsiDisplay.Default, display)).IsEqualTo(new Interaction(InteractionKind.Url, "mudclient://look"));
+		await Assert.That(FirstInteraction(VtDecoding.Terminal.CreateDecoder().Feed(MudLink), AnsiDisplay.Default, display)).IsNull();
+	}
+
+	[Test]
+	public async Task Diagnostics_AreReportedAsMetrics()
+	{
+		var services = new ServiceCollection().AddMetrics().BuildServiceProvider();
+		var meters = services.GetRequiredService<IMeterFactory>();
+		var seen = new List<(long Value, string Kind)>();
+		using var listener = new MeterListener();
+		listener.InstrumentPublished = (instrument, l) =>
+		{
+			if (instrument.Meter.Name == "MarkupString.Decoding" && instrument.Meter.Scope == meters) l.EnableMeasurementEvents(instrument);
+		};
+		listener.SetMeasurementEventCallback<long>((_, value, tags, _) => seen.Add((value, (string)tags[0].Value!)));
+		listener.Start();
+
+		var decoder = VtDecoding.Terminal.CreateDecoder(new DecoderOptions { Meters = meters });
+		decoder.Feed("\e[5;5H\e]777;x\a");
+
+		await Assert.That(seen).IsEquivalentTo([(1L, "unhandled-sequence"), (1L, "unhandled-sequence")]);
+	}
+
+	[Test]
+	public async Task AddMarkupString_RegistersEverything()
+	{
+		using var services = new ServiceCollection()
+			.AddMarkupString(options => options.Pictures.MaxPixels = 100)
+			.AddDecoders(registry => registry.WithMxp())
+			.Services.BuildServiceProvider();
+
+		var factory = services.GetRequiredService<IDecoderFactory>();
+		var first = factory.CreateDecoder();
+		var second = factory.CreateDecoder();
+		await Assert.That(first.Registry.Has(MxpDecoding.Protocol)).IsTrue();
+		await Assert.That(first.Pictures().Cache).IsSameReferenceAs(second.Pictures().Cache);
+		await Assert.That(first.Pictures().Cache).IsSameReferenceAs(services.GetRequiredService<IPictureCache>());
+		await Assert.That(first.Pictures().MaxPixels).IsEqualTo(100);
+		await Assert.That(services.GetRequiredService<IStyleResolver>()).IsSameReferenceAs(services.GetRequiredService<DisplayRegistry>());
+		await Assert.That(services.GetRequiredService<MarkupRegistry>()).IsNotNull();
+	}
+
+	[Test]
+	public async Task AddMarkupString_BindsConfiguration()
+	{
+		var configuration = new ConfigurationBuilder().AddInMemoryCollection(new Dictionary<string, string?>
+		{
+			["MarkupString:LinkSchemes:0"] = "mudclient",
+			["MarkupString:Display:Output"] = "CellGrid",
+			["MarkupString:Display:Colors"] = "Standard",
+			["MarkupString:Decoding:MaxLineLength"] = "80",
+			["MarkupString:Pictures:Budget"] = "1000",
+		}).Build();
+		using var services = new ServiceCollection()
+			.AddSingleton<IConfiguration>(configuration)
+			.AddMarkupString().BindConfiguration()
+			.Services.BuildServiceProvider();
+
+		var display = services.GetRequiredService<DisplayOptions>();
+		await Assert.That(display.Capabilities).IsEqualTo(OutputCapabilities.CellGrid with { Colors = ColorLevel.Standard });
+		await Assert.That(((MemoryPictureCache)services.GetRequiredService<IPictureCache>()).Budget).IsEqualTo(1000);
+		var decoder = services.GetRequiredService<IDecoderFactory>().CreateDecoder();
+		await Assert.That(decoder.Options.MaxLineLength).IsEqualTo(80);
+		var lines = decoder.Feed(MudLink);
+		await Assert.That(FirstInteraction(lines, services.GetRequiredService<IStyleResolver>(), display)?.Target).IsEqualTo("mudclient://look");
+	}
+
+	private sealed class NoCache : IPictureCache
+	{
+		public bool TryGet(string key, [NotNullWhen(true)] out StoredPicture? picture)
+		{
+			picture = null;
+			return false;
+		}
+
+		public void Set(StoredPicture picture)
+		{
+		}
+
+		public bool Remove(string key) => false;
+	}
+
+	[Test]
+	public async Task AddMarkupString_TakesAPictureCacheOfYourOwn()
+	{
+		using var services = new ServiceCollection().AddMarkupString().UsePictureCache<NoCache>().Services.BuildServiceProvider();
+		await Assert.That(services.GetRequiredService<IDecoderFactory>().CreateDecoder().Pictures().Cache).IsTypeOf<NoCache>();
+	}
+}
diff --git a/MarkupString.Tests/MarkupString.Tests.csproj b/MarkupString.Tests/MarkupString.Tests.csproj
index aa858d5..9686a2c 100644
--- a/MarkupString.Tests/MarkupString.Tests.csproj
+++ b/MarkupString.Tests/MarkupString.Tests.csproj
@@ -10,6 +10,9 @@
   <ItemGroup>
     <PackageReference Include="CsCheck" Version="5.0.0" />
     <PackageReference Include="TUnit" Version="1.78.0" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Diagnostics" Version="10.0.0" />
     <!-- A GitHub-flavoured Markdown reader, so the Markdown tests check what a reader makes of the output
          rather than only the characters written. -->
     <PackageReference Include="Markdig" Version="1.5.1" />
@@ -21,6 +24,7 @@
   <ItemGroup>
     <ProjectReference Include="..\MarkupString\MarkupString.csproj" />
     <ProjectReference Include="..\MarkupString.Ansi\MarkupString.Ansi.csproj" />
+    <ProjectReference Include="..\MarkupString.Extensions.DependencyInjection\MarkupString.Extensions.DependencyInjection.csproj" />
     <ProjectReference Include="..\MarkupString.Html\MarkupString.Html.csproj" />
     <ProjectReference Include="..\MarkupString.Mxp\MarkupString.Mxp.csproj" />
     <ProjectReference Include="..\MarkupString.Pueblo\MarkupString.Pueblo.csproj" />
diff --git a/MarkupString.slnx b/MarkupString.slnx
index 5ea97db..9b5c4a4 100644
--- a/MarkupString.slnx
+++ b/MarkupString.slnx
@@ -1,6 +1,7 @@
 <Solution>
   <Project Path="MarkupString.Ansi/MarkupString.Ansi.csproj" />
   <Project Path="MarkupString.AotSmoke/MarkupString.AotSmoke.csproj" />
+  <Project Path="MarkupString.Extensions.DependencyInjection/MarkupString.Extensions.DependencyInjection.csproj" />
   <Project Path="MarkupString.Html/MarkupString.Html.csproj" />
   <Project Path="MarkupString.Mxp/MarkupString.Mxp.csproj" />
   <Project Path="MarkupString.Pueblo/MarkupString.Pueblo.csproj" />
diff --git a/MarkupString/Decoding/Decoder.cs b/MarkupString/Decoding/Decoder.cs
index acb89ca..e905b4b 100644
--- a/MarkupString/Decoding/Decoder.cs
+++ b/MarkupString/Decoding/Decoder.cs
@@ -23,6 +23,7 @@ internal Decoder(DecoderRegistry registry, DecoderOptions options)
 		Registry = registry;
 		Options = options;
 		Identity = options.Identity;
+		Diagnostics = new DecodeDiagnostics(DecodeMetrics.For(options.Meters));
 		_tokenizer = new VtTokenizer(options.Limits);
 		Context = new DecodeContext(this);
 		_sink = new Sink(this);
@@ -38,7 +39,7 @@ internal Decoder(DecoderRegistry registry, DecoderOptions options)
 	public ClientIdentity Identity { get; set; }
 
 	/// <summary>Counts of what was dropped, for a diagnostics view.</summary>
-	public DecodeDiagnostics Diagnostics { get; } = new();
+	public DecodeDiagnostics Diagnostics { get; }
 
 	/// <summary>Raised for each event, as it is found.</summary>
 	public event Action<DecodeEvent>? EventRaised;
@@ -224,21 +225,79 @@ public void Apc(ReadOnlySpan<char> payload)
 	}
 }
 
-/// <summary>Counts of what a decoder dropped.</summary>
+/// <summary>
+/// Counts of what a decoder dropped. Each is also reported on the <c>MarkupString.Decoding</c> meter, as the
+/// counter <c>markupstring.decoding.dropped</c> tagged with its <c>kind</c>.
+/// </summary>
 public sealed class DecodeDiagnostics
 {
+	private readonly DecodeMetrics? _metrics;
+	private int _abandoned, _unhandled, _controls, _limits, _pictures;
+
+	/// <summary>Counts that are not reported anywhere.</summary>
+	public DecodeDiagnostics()
+	{
+	}
+
+	internal DecodeDiagnostics(DecodeMetrics metrics) => _metrics = metrics;
+
 	/// <summary>Sequences that were malformed, too long, or cut off by a line ending.</summary>
-	public int AbandonedSequences { get; set; }
+	public int AbandonedSequences
+	{
+		get => _abandoned;
+		set => _abandoned = Report(_abandoned, value, "abandoned-sequence");
+	}
 
 	/// <summary>Well-formed sequences no handler claimed.</summary>
-	public int UnhandledSequences { get; set; }
+	public int UnhandledSequences
+	{
+		get => _unhandled;
+		set => _unhandled = Report(_unhandled, value, "unhandled-sequence");
+	}
 
 	/// <summary>Control characters no handler claimed.</summary>
-	public int UnhandledControls { get; set; }
+	public int UnhandledControls
+	{
+		get => _controls;
+		set => _controls = Report(_controls, value, "unhandled-control");
+	}
 
 	/// <summary>Things dropped because a limit was reached: an element stack, a line length, a picture size.</summary>
-	public int LimitsReached { get; set; }
+	public int LimitsReached
+	{
+		get => _limits;
+		set => _limits = Report(_limits, value, "limit");
+	}
 
 	/// <summary>Pictures that could not be decoded.</summary>
-	public int PicturesFailed { get; set; }
+	public int PicturesFailed
+	{
+		get => _pictures;
+		set => _pictures = Report(_pictures, value, "picture");
+	}
+
+	private int Report(int before, int after, string kind)
+	{
+		if (after > before) _metrics?.Dropped(after - before, kind);
+		return after;
+	}
+}
+
+/// <summary>The decoding meter, one for each meter factory.</summary>
+internal sealed class DecodeMetrics
+{
+	public const string MeterName = "MarkupString.Decoding";
+
+	private static readonly DecodeMetrics Shared = new(new System.Diagnostics.Metrics.Meter(MeterName));
+	private static readonly System.Runtime.CompilerServices.ConditionalWeakTable<System.Diagnostics.Metrics.IMeterFactory, DecodeMetrics> ByFactory = [];
+
+	private readonly System.Diagnostics.Metrics.Counter<long> _dropped;
+
+	private DecodeMetrics(System.Diagnostics.Metrics.Meter meter) =>
+		_dropped = meter.CreateCounter<long>("markupstring.decoding.dropped", "{item}", "What decoders dropped, by kind.");
+
+	public static DecodeMetrics For(System.Diagnostics.Metrics.IMeterFactory? factory) =>
+		factory is null ? Shared : ByFactory.GetValue(factory, static f => new DecodeMetrics(f.Create(new System.Diagnostics.Metrics.MeterOptions(MeterName))));
+
+	public void Dropped(int count, string kind) => _dropped.Add(count, new KeyValuePair<string, object?>("kind", kind));
 }
diff --git a/MarkupString/Decoding/DecoderRegistry.cs b/MarkupString/Decoding/DecoderRegistry.cs
index 1c826a8..a53a7c9 100644
--- a/MarkupString/Decoding/DecoderRegistry.cs
+++ b/MarkupString/Decoding/DecoderRegistry.cs
@@ -157,7 +157,7 @@ private static void Add<TKey, T>(Dictionary<TKey, List<T>> table, TKey key, T ha
 /// The protocols a decoder reads, built once and shared. Each connection makes its own <see cref="Decoder"/> from
 /// it, which holds that connection's state.
 /// </summary>
-public sealed class DecoderRegistry
+public sealed class DecoderRegistry : IDecoderFactory
 {
 	private readonly IDecoderPlugin[] _plugins;
 
@@ -226,4 +226,20 @@ public sealed record DecoderOptions
 
 	/// <summary>The longest line, in characters; a longer line is ended there and the rest starts a new one.</summary>
 	public int MaxLineLength { get; init; } = 64 * 1024;
+
+	/// <summary>Which link addresses a server may send; one it may not is read as text. <see cref="UrlPolicy.Safe"/> unless set.</summary>
+	public IUrlPolicy Links { get; init; } = UrlPolicy.Safe;
+
+	/// <summary>
+	/// Where <see cref="DecodeDiagnostics"/> are reported as metrics (the <c>MarkupString.Decoding</c> meter), or null
+	/// for the shared meter. Pass the host's, as ASP.NET Core registers one.
+	/// </summary>
+	public System.Diagnostics.Metrics.IMeterFactory? Meters { get; init; }
+}
+
+/// <summary>Makes a <see cref="Decoder"/> for each connection: a <see cref="DecoderRegistry"/>, or a host's own.</summary>
+public interface IDecoderFactory
+{
+	/// <summary>A decoder for one connection.</summary>
+	Decoder CreateDecoder(DecoderOptions? options = null);
 }
diff --git a/MarkupString/Display/CellRenderer.cs b/MarkupString/Display/CellRenderer.cs
index d6a849d..eed9940 100644
--- a/MarkupString/Display/CellRenderer.cs
+++ b/MarkupString/Display/CellRenderer.cs
@@ -95,7 +95,7 @@ public static class CellRenderer
 	/// <param name="registry">The styles.</param>
 	/// <param name="options">The output.</param>
 	/// <param name="wordWrap">Wrap at the last space that fits, rather than at the last cell.</param>
-	public static CellLayout Layout(MarkupText text, int columns, DisplayRegistry registry, DisplayOptions options, bool wordWrap = false)
+	public static CellLayout Layout(MarkupText text, int columns, IStyleResolver registry, DisplayOptions options, bool wordWrap = false)
 	{
 		ArgumentNullException.ThrowIfNull(text);
 		ArgumentNullException.ThrowIfNull(registry);
diff --git a/MarkupString/Display/DisplayRegistry.cs b/MarkupString/Display/DisplayRegistry.cs
index 25fac54..6f6eb47 100644
--- a/MarkupString/Display/DisplayRegistry.cs
+++ b/MarkupString/Display/DisplayRegistry.cs
@@ -4,7 +4,7 @@ namespace MarkupString.Display;
 /// The style contributors a structured renderer folds markup with. Immutable; build one once with
 /// <c>With(...)</c> and share it.
 /// </summary>
-public sealed class DisplayRegistry
+public sealed class DisplayRegistry : IStyleResolver
 {
 	private readonly IStyleContributor[] _contributors;
 
diff --git a/MarkupString/Display/DisplayStyle.cs b/MarkupString/Display/DisplayStyle.cs
index fe78269..6b6de1b 100644
--- a/MarkupString/Display/DisplayStyle.cs
+++ b/MarkupString/Display/DisplayStyle.cs
@@ -126,6 +126,13 @@ public interface IStyleContributor
 	void Contribute(MarkupSet markups, StyleBuilder style, DisplayOptions options);
 }
 
+/// <summary>Turns a run's markup into the style an output draws it with: a <see cref="DisplayRegistry"/>, or a host's own.</summary>
+public interface IStyleResolver
+{
+	/// <summary>Folds <paramref name="markups"/> into one style, degraded to what <paramref name="options"/> can show.</summary>
+	DisplayStyle Resolve(MarkupSet? markups, DisplayOptions options);
+}
+
 /// <summary>Turns a palette colour into RGB, so a client's theme decides what "red" is.</summary>
 public interface IColorResolver
 {
@@ -151,6 +158,9 @@ public sealed record DisplayOptions
 	/// <summary>How palette colours become RGB, or null for the xterm palette.</summary>
 	public IColorResolver? Colors { get; init; }
 
+	/// <summary>Which link addresses become clickable; one that may not stays text. <see cref="UrlPolicy.Safe"/> unless set.</summary>
+	public IUrlPolicy Links { get; init; } = UrlPolicy.Safe;
+
 	/// <summary>The default text colour, used when inverse text has no colour of its own.</summary>
 	public RgbColor DefaultForeground { get; init; } = new(229, 229, 229);
 
diff --git a/MarkupString/Display/SpanRenderer.cs b/MarkupString/Display/SpanRenderer.cs
index 060548b..ddc7118 100644
--- a/MarkupString/Display/SpanRenderer.cs
+++ b/MarkupString/Display/SpanRenderer.cs
@@ -21,7 +21,7 @@ public readonly record struct DisplaySpan(string Text, DisplayStyle Style)
 public static class SpanRenderer
 {
 	/// <summary>The spans of <paramref name="text"/>, in order.</summary>
-	public static IReadOnlyList<DisplaySpan> Render(MarkupText text, DisplayRegistry registry, DisplayOptions options)
+	public static IReadOnlyList<DisplaySpan> Render(MarkupText text, IStyleResolver registry, DisplayOptions options)
 	{
 		ArgumentNullException.ThrowIfNull(text);
 		ArgumentNullException.ThrowIfNull(registry);
diff --git a/MarkupString/PublicAPI.Unshipped.txt b/MarkupString/PublicAPI.Unshipped.txt
index 20eefc5..b3965c1 100644
--- a/MarkupString/PublicAPI.Unshipped.txt
+++ b/MarkupString/PublicAPI.Unshipped.txt
@@ -640,7 +640,6 @@ static MarkupString.Display.Cell.operator !=(MarkupString.Display.Cell left, Mar
 static MarkupString.Display.Cell.operator ==(MarkupString.Display.Cell left, MarkupString.Display.Cell right) -> bool
 static MarkupString.Display.CellPoint.operator !=(MarkupString.Display.CellPoint left, MarkupString.Display.CellPoint right) -> bool
 static MarkupString.Display.CellPoint.operator ==(MarkupString.Display.CellPoint left, MarkupString.Display.CellPoint right) -> bool
-static MarkupString.Display.CellRenderer.Layout(MarkupString.MarkupText! text, int columns, MarkupString.Display.DisplayRegistry! registry, MarkupString.Display.DisplayOptions! options, bool wordWrap = false) -> MarkupString.Display.CellLayout!
 static MarkupString.Display.DisplayOptions.operator !=(MarkupString.Display.DisplayOptions? left, MarkupString.Display.DisplayOptions? right) -> bool
 static MarkupString.Display.DisplayOptions.operator ==(MarkupString.Display.DisplayOptions? left, MarkupString.Display.DisplayOptions? right) -> bool
 static MarkupString.Display.DisplayRegistry.Core.get -> MarkupString.Display.DisplayRegistry!
@@ -655,7 +654,6 @@ static MarkupString.Display.Interaction.operator ==(MarkupString.Display.Interac
 static MarkupString.Display.SpanRenderer.Css(MarkupString.Display.DisplayStyle style) -> string!
 static MarkupString.Display.SpanRenderer.CssClasses(MarkupString.Display.DisplayStyle style) -> string!
 static MarkupString.Display.SpanRenderer.Hex(MarkupString.RgbColor color) -> string!
-static MarkupString.Display.SpanRenderer.Render(MarkupString.MarkupText! text, MarkupString.Display.DisplayRegistry! registry, MarkupString.Display.DisplayOptions! options) -> System.Collections.Generic.IReadOnlyList<MarkupString.Display.DisplaySpan>!
 static MarkupString.Display.VocabularyStyles.Instance.get -> MarkupString.Display.VocabularyStyles!
 static MarkupString.HighlightMarkup.operator !=(MarkupString.HighlightMarkup? left, MarkupString.HighlightMarkup? right) -> bool
 static MarkupString.HighlightMarkup.operator ==(MarkupString.HighlightMarkup? left, MarkupString.HighlightMarkup? right) -> bool
@@ -739,3 +737,22 @@ override MarkupString.LinkGroupMarkup.GetHashCode() -> int
 override MarkupString.LinkGroupMarkup.ToString() -> string!
 static MarkupString.LinkGroupMarkup.operator !=(MarkupString.LinkGroupMarkup? left, MarkupString.LinkGroupMarkup? right) -> bool
 static MarkupString.LinkGroupMarkup.operator ==(MarkupString.LinkGroupMarkup? left, MarkupString.LinkGroupMarkup? right) -> bool
+MarkupString.Decoding.DecoderOptions.Links.get -> MarkupString.IUrlPolicy!
+MarkupString.Decoding.DecoderOptions.Links.init -> void
+MarkupString.Decoding.DecoderOptions.Meters.get -> System.Diagnostics.Metrics.IMeterFactory?
+MarkupString.Decoding.DecoderOptions.Meters.init -> void
+MarkupString.Decoding.IDecoderFactory
+MarkupString.Decoding.IDecoderFactory.CreateDecoder(MarkupString.Decoding.DecoderOptions? options = null) -> MarkupString.Decoding.Decoder!
+MarkupString.Display.DisplayOptions.Links.get -> MarkupString.IUrlPolicy!
+MarkupString.Display.DisplayOptions.Links.init -> void
+MarkupString.Display.IStyleResolver
+MarkupString.Display.IStyleResolver.Resolve(MarkupString.MarkupSet? markups, MarkupString.Display.DisplayOptions! options) -> MarkupString.Display.DisplayStyle
+MarkupString.IUrlPolicy
+MarkupString.IUrlPolicy.IsAllowed(string! url) -> bool
+MarkupString.UrlPolicy
+MarkupString.UrlPolicy.IsAllowed(string! url) -> bool
+MarkupString.UrlPolicy.Schemes.get -> System.Collections.Generic.IReadOnlyCollection<string!>!
+static MarkupString.Display.CellRenderer.Layout(MarkupString.MarkupText! text, int columns, MarkupString.Display.IStyleResolver! registry, MarkupString.Display.DisplayOptions! options, bool wordWrap = false) -> MarkupString.Display.CellLayout!
+static MarkupString.Display.SpanRenderer.Render(MarkupString.MarkupText! text, MarkupString.Display.IStyleResolver! registry, MarkupString.Display.DisplayOptions! options) -> System.Collections.Generic.IReadOnlyList<MarkupString.Display.DisplaySpan>!
+static MarkupString.UrlPolicy.Safe.get -> MarkupString.UrlPolicy!
+static MarkupString.UrlPolicy.WithSchemes(params System.Collections.Generic.IEnumerable<string!>! schemes) -> MarkupString.UrlPolicy!
diff --git a/MarkupString/UrlPolicy.cs b/MarkupString/UrlPolicy.cs
new file mode 100644
index 0000000..480cb3d
--- /dev/null
+++ b/MarkupString/UrlPolicy.cs
@@ -0,0 +1,47 @@
+namespace MarkupString;
+
+/// <summary>Which link addresses may become something a client navigates to.</summary>
+public interface IUrlPolicy
+{
+	/// <summary>Whether <paramref name="url"/> may be a link. One that may not is shown as its text.</summary>
+	bool IsAllowed(string url);
+}
+
+/// <summary>
+/// The usual <see cref="IUrlPolicy"/>: relative addresses and <c>http</c>, <c>https</c>, <c>mailto</c>, <c>ftp</c>,
+/// <c>ftps</c> and <c>tel</c>, with whatever other schemes it is made with. <c>javascript:</c>, <c>data:</c>,
+/// <c>vbscript:</c> and <c>file:</c> are never allowed.
+/// </summary>
+public sealed class UrlPolicy : IUrlPolicy
+{
+	private static readonly string[] Usual = ["http", "https", "mailto", "ftp", "ftps", "tel"];
+	private static readonly string[] Never = ["javascript", "data", "vbscript", "file"];
+
+	private readonly HashSet<string> _schemes;
+
+	private UrlPolicy(IEnumerable<string> schemes) => _schemes = new HashSet<string>(schemes, StringComparer.OrdinalIgnoreCase);
+
+	/// <summary>The usual schemes only.</summary>
+	public static UrlPolicy Safe { get; } = new(Usual);
+
+	/// <summary>The usual schemes and <paramref name="schemes"/> (such as <c>mudclient</c>), without the colon.</summary>
+	public static UrlPolicy WithSchemes(params IEnumerable<string> schemes)
+	{
+		ArgumentNullException.ThrowIfNull(schemes);
+		return new UrlPolicy(Usual.Concat(schemes.Where(scheme => !Never.Contains(scheme, StringComparer.OrdinalIgnoreCase))));
+	}
+
+	/// <summary>The schemes it allows.</summary>
+	public IReadOnlyCollection<string> Schemes => _schemes;
+
+	/// <inheritdoc/>
+	public bool IsAllowed(string url)
+	{
+		if (string.IsNullOrWhiteSpace(url)) return false;
+		if (!Uri.TryCreate(url, UriKind.RelativeOrAbsolute, out var uri)) return false;
+
+		// A relative URL or a bare fragment cannot name a scheme, so there is none to distrust.
+		if (!uri.IsAbsoluteUri) return true;
+		return _schemes.Contains(uri.Scheme);
+	}
+}
diff --git a/README.md b/README.md
index 8cf48c3..a9d54ba 100644
--- a/README.md
+++ b/README.md
@@ -165,11 +165,13 @@ rendering opinions.
 | [`MarkupString.Html`](https://www.nuget.org/packages/MarkupString.Html) | Checked raw HTML markup with configurable tag policies for trusted and untrusted input. |
 | [`MarkupString.Mxp`](https://www.nuget.org/packages/MarkupString.Mxp) | The shared vocabulary expressed as client-supported MXP elements. |
 | [`MarkupString.Pueblo`](https://www.nuget.org/packages/MarkupString.Pueblo) | The shared vocabulary expressed through Pueblo client extensions. |
+| [`MarkupString.Extensions.DependencyInjection`](https://www.nuget.org/packages/MarkupString.Extensions.DependencyInjection) | `AddMarkupString()` for ASP.NET Core and other `Microsoft.Extensions` hosts, with options bound from configuration. |
 
 ```sh
 dotnet add package MarkupString.Html
 dotnet add package MarkupString.Mxp
 dotnet add package MarkupString.Pueblo
+dotnet add package MarkupString.Extensions.DependencyInjection
 ```
 
 All packages share one version and are released together.
@@ -230,6 +232,7 @@ reflection hidden behind convenience APIs.
 | [Serialization](docs/serialization.md) | JSON wire format, forward compatibility, and `UnknownMarkup`. |
 | [Decoding](docs/decoding.md) | Reading server output: ANSI and VT sequences, OSC, events, replies, limits, and plugins. |
 | [Display](docs/display.md) | Output capabilities, degrading, spans for a web page, and cell grids with hit testing. |
+| [Dependency injection](docs/dependency-injection.md) | `AddMarkupString()`, configuration, a shared picture cache, link policy, metrics, and the interfaces to replace. |
 | [Releasing](docs/releasing.md) | Versioning and publishing for maintainers. |
 
 ## Requirements
diff --git a/docs/decoding.md b/docs/decoding.md
index da07b8e..431f9a7 100644
--- a/docs/decoding.md
+++ b/docs/decoding.md
@@ -177,7 +177,7 @@ Decoder.DecodeAll("\e(0lqqk\e(B ok", registry)[0].Content;  // ┌──┐ ok
 | `10`, `11`, `12` | Set the foreground, background, cursor colour, or answer `?` (10 and 11 only). `10;a;b` sets 10 and 11 at once. |
 | `110`, `111`, `112` | Reset them |
 | `52;sel;base64` | `ClipboardEvent` with the decoded text, or a null text for `?`. Invalid base64 is dropped. |
-| `8;params;uri` | A link over the text that follows, until an empty uri. An address longer than 2083 characters, or one `UrlSafety.IsSafeNavigableUrl` refuses (`javascript:` and the like), ends the link instead. An `id=` among the params becomes a `LinkGroupMarkup`, and so `Interaction.Group`: the text under it is one link even across lines. |
+| `8;params;uri` | A link over the text that follows, until an empty uri. An address longer than 2083 characters, or one `UrlSafety.IsSafeNavigableUrl` refuses (`javascript:` and the like), ends the link instead. The address must pass `DecoderOptions.Links` (`UrlPolicy.Safe` unless set). An `id=` among the params becomes a `LinkGroupMarkup`, and so `Interaction.Group`: the text under it is one link even across lines. |
 | `68;1;SEND;command` | An MSLP command link over the underlined text that follows. Turning the underline off ends it, and so does the end of the line. |
 
 Colours are X11 specs: `rgb:r/g/b` with one to four hex digits a channel, or `#rgb`, `#rrggbb`,
@@ -236,6 +236,8 @@ so a bare `ESC ]` typed into a channel cannot swallow the rest of the session.
 |---|---|---|
 | `MaxOpenElements` | 64 | Elements a text protocol may have open at once |
 | `MaxLineLength` | 65536 | Characters in a line. A longer line is ended at the limit and the rest starts the next line. |
+| `Links` | `UrlPolicy.Safe` | Which link addresses a server's links may have; any other is read as text |
+| `Meters` | null | The `IMeterFactory` the diagnostics are reported to; null uses a shared meter |
 
 `decoder.Diagnostics` counts what was dropped:
 
@@ -248,7 +250,11 @@ decoder.Feed("\e[?25lHello\e]0;never closed\nworld\u0001\n");
 ```
 
 `LimitsReached` counts lines broken at the limit and elements refused. `PicturesFailed` counts pictures that
-could not be decoded.
+could not be decoded. Each count is also reported as the metric `markupstring.decoding.dropped` on the
+`MarkupString.Decoding` meter, tagged with its `kind`; see [Dependency injection](dependency-injection.md#metrics).
+
+`DecoderRegistry` is an `IDecoderFactory`, so code that makes decoders can take the interface and a
+test or host can give it another.
 
 ## Client identity and answers
 
diff --git a/docs/dependency-injection.md b/docs/dependency-injection.md
new file mode 100644
index 0000000..bb70fef
--- /dev/null
+++ b/docs/dependency-injection.md
@@ -0,0 +1,84 @@
+# Dependency injection
+
+Everything in MarkupString can be built by hand: the registries are immutable values, and options are
+records. A host that uses `Microsoft.Extensions.DependencyInjection` (ASP.NET Core, the generic host)
+can instead register it all at once with `MarkupString.Extensions.DependencyInjection`.
+
+```csharp
+builder.Services.AddMarkupString()
+    .BindConfiguration()                                     // the "MarkupString" section
+    .AddDecoders(registry => registry.WithMxp().WithPueblo())
+    .AddMarkup(registry => registry.WithHtml().WithMxp().WithPueblo());
+builder.Services.AddMetrics();                               // optional: decode metrics on the host's meter factory
+```
+
+Then, for each connection:
+
+```csharp
+public sealed class Connection(MarkupDecoderFactory decoders, IStyleResolver styles, DisplayOptions display)
+{
+    private readonly Decoder _decoder = decoders.CreateDecoderFor(new ClientIdentity { Columns = 100 });
+
+    public IEnumerable<IReadOnlyList<DisplaySpan>> Receive(string text) =>
+        _decoder.Feed(text).Select(line => SpanRenderer.Render(line.Content, styles, display));
+}
+```
+
+## What is registered
+
+Every service is a singleton, added only when nothing of that type is registered yet, so registering
+your own first replaces it.
+
+| Service | What it is |
+|---|---|
+| `MarkupRegistry` | `MarkupRegistry.Empty.WithAnsi()` and each `AddMarkup` step |
+| `DecoderRegistry` | `WithVt()`, `WithPictures(cache)` unless pictures are off, and each `AddDecoders` step |
+| `MarkupDecoderFactory`, `IDecoderFactory` | Makes a decoder per connection with the configured limits, link policy, metrics and picture size |
+| `IPictureCache` | One `MemoryPictureCache` that every connection shares |
+| `DisplayRegistry`, `IStyleResolver` | `DisplayRegistry.Core.WithAnsi()` and each `AddDisplay` step |
+| `DisplayOptions` | The configured output, colour level and link policy |
+| `IUrlPolicy` | `UrlPolicy.WithSchemes(LinkSchemes)` |
+
+`UsePictureCache<T>()` and `UseUrlPolicy<T>()` swap in your own as singletons. A cache of your own
+(on disk, in Redis) must be safe to call from several threads; see [Pictures](decoding.md#pictures).
+
+## Configuration
+
+`AddMarkupString(options => …)` sets `MarkupStringOptions` in code, and `BindConfiguration(path)`
+binds it from configuration. The binder is source-generated, so it works in a native AOT app.
+
+```json
+{
+  "MarkupString": {
+    "LinkSchemes": [ "mudclient" ],
+    "Decoding": { "MaxLineLength": 65536, "MaxOpenElements": 64, "AnswerCursorPosition": false },
+    "Pictures": { "Enabled": true, "Budget": 268435456, "MaxPixels": 16777216 },
+    "Display": { "Output": "Browser", "Colors": "Xterm256", "BoldIsBright": false }
+  }
+}
+```
+
+`Display:Output` is `Browser`, `CellGrid` or `PlainText`; `Display:Colors`, when set, lowers its
+colour level. The options are read once, when each service is first made.
+
+## The interfaces underneath
+
+These are in the core packages and need no container.
+
+- `IDecoderFactory`: `CreateDecoder(options)`. `DecoderRegistry` implements it.
+- `IStyleResolver`: `Resolve(markups, options)`. `DisplayRegistry` implements it, and `SpanRenderer`
+  and `CellRenderer` take one.
+- `IUrlPolicy`: which link addresses are allowed. `UrlPolicy.Safe` is the default;
+  `UrlPolicy.WithSchemes("mudclient")` adds schemes, never `javascript`, `data`, `vbscript` or `file`.
+  Set it as `DecoderOptions.Links` (what a server's links become) and `DisplayOptions.Links` (what is
+  drawn as clickable). The writers still use `UrlSafety`.
+- `IPictureCache`: where decoded pictures are kept; `WithPictures(cache)` shares one.
+- `IColorResolver`: how palette colours become RGB, as `DisplayOptions.Colors`.
+
+## Metrics
+
+Each decoder reports what it drops on the `MarkupString.Decoding` meter, as the counter
+`markupstring.decoding.dropped` with a `kind` tag: `abandoned-sequence`, `unhandled-sequence`,
+`unhandled-control`, `limit` or `picture`. With `DecoderOptions.Meters` (the factory sets it to the
+host's `IMeterFactory` when one is registered) the meter comes from that factory, so
+`dotnet-counters` and OpenTelemetry see it with the host's other meters.
diff --git a/docs/display.md b/docs/display.md
index 774040b..16bdb41 100644
--- a/docs/display.md
+++ b/docs/display.md
@@ -144,8 +144,12 @@ per markup set in a text.
 | `Colors` | null | An `IColorResolver`; null uses the xterm palette |
 | `DefaultForeground` | `(229, 229, 229)` | Used when inverse text has no colour of its own |
 | `DefaultBackground` | `(0, 0, 0)` | Used when inverse text has no background of its own |
+| `Links` | `UrlPolicy.Safe` | Which link addresses are drawn as clickable; any other stays text |
 | `TabWidth` | 8 | Cells between tab stops, in `CellRenderer` |
 
+`SpanRenderer` and `CellRenderer` take an `IStyleResolver`, which a `DisplayRegistry` is, so a host can
+give them its own.
+
 An `IColorResolver` decides what "red" is. Subclass `AnsiColors` to change part of the palette:
 
 ```csharp

From e9765d97a78c2528974fdabe9fac51d89329fa2c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 23:22:17 +0000
Subject: [PATCH 18/19] Ask IUrlPolicy in every writer, and log what decoders
 drop

MarkupRegistry.WithLinks sets the policy the ANSI (OSC 8, MSLP), HTML, MXP,
Pueblo, BBCode and Markdown writers ask; HtmlTagPolicy.Links does the same for
checked tags. DecodeDiagnostics.Dropped reports each drop, and the DI factory
logs it at debug level through the host's ILoggerFactory.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rqqt7WGskvSsoRXvKMqybx
---
 CHANGELOG.md                                  |  6 +-
 .../Emitters/AnsiBBCodeEmitter.cs             |  2 +-
 .../Emitters/AnsiEmitterSupport.cs            | 13 ++--
 MarkupString.Ansi/Emitters/AnsiHtmlEmitter.cs |  8 +--
 .../Emitters/AnsiMarkdownEmitter.cs           | 10 +--
 MarkupString.Ansi/Emitters/AnsiSetEmitter.cs  |  2 +-
 ...ring.Extensions.DependencyInjection.csproj |  1 +
 .../PublicAPI.Unshipped.txt                   |  2 +-
 .../ServiceCollectionExtensions.cs            | 23 ++++--
 MarkupString.Html/HtmlTagPolicy.cs            |  9 ++-
 MarkupString.Html/PublicAPI.Unshipped.txt     |  2 +
 MarkupString.Tests/Decoding/InjectionTests.cs | 71 +++++++++++++++++++
 MarkupString.Tests/MarkupString.Tests.csproj  |  1 +
 MarkupString/Decoding/Decoder.cs              | 49 ++++++++++---
 MarkupString/MarkupRegistry.cs                | 28 ++++++--
 MarkupString/PublicAPI.Unshipped.txt          |  9 +++
 docs/decoding.md                              |  4 +-
 docs/dependency-injection.md                  | 15 ++--
 docs/formats.md                               |  4 +-
 19 files changed, 207 insertions(+), 52 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f4aae04..8ece7bb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -39,9 +39,11 @@ follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   [Dependency injection](docs/dependency-injection.md).
 - Interfaces to inject: `IDecoderFactory` (a `DecoderRegistry` is one), `IStyleResolver` (a `DisplayRegistry` is one;
   `SpanRenderer` and `CellRenderer` take it), and `IUrlPolicy` with `UrlPolicy.Safe` and `UrlPolicy.WithSchemes`, set as
-  `DecoderOptions.Links` and `DisplayOptions.Links`.
+  `DecoderOptions.Links`, `DisplayOptions.Links`, `MarkupRegistry.WithLinks` (every writer asks it) and
+  `HtmlTagPolicy.Links`.
 - Decode diagnostics are reported on the `MarkupString.Decoding` meter (`markupstring.decoding.dropped`, by `kind`),
-  through `DecoderOptions.Meters` when a host gives its `IMeterFactory`.
+  through `DecoderOptions.Meters` when a host gives its `IMeterFactory`, and raised as `DecodeDiagnostics.Dropped`;
+  the DI package logs them at debug level to the host's `ILoggerFactory`.
 - `IPictureCache` and `MemoryPictureCache`: `WithPictures(cache)` shares decoded pictures between connections, and a
   host can keep them in a cache of its own.
 - Kitty animation frames (`a=f`, and frame times with `a=a`) decode into a moving `StoredPicture`, given as a GIF.
diff --git a/MarkupString.Ansi/Emitters/AnsiBBCodeEmitter.cs b/MarkupString.Ansi/Emitters/AnsiBBCodeEmitter.cs
index 56b69f1..870211c 100644
--- a/MarkupString.Ansi/Emitters/AnsiBBCodeEmitter.cs
+++ b/MarkupString.Ansi/Emitters/AnsiBBCodeEmitter.cs
@@ -31,7 +31,7 @@ private static void WriteTags(in AnsiStyle style, ReadOnlySpan<char> body, in Em
 
 		var link = style.LinkKind == LinkKind.Url
 			&& style.LinkUrl is { Length: > 0 } candidate
-			&& UrlSafety.IsSafeNavigableUrl(candidate)
+			&& context.Registry.Links.IsAllowed(candidate)
 			? candidate
 			: null;
 
diff --git a/MarkupString.Ansi/Emitters/AnsiEmitterSupport.cs b/MarkupString.Ansi/Emitters/AnsiEmitterSupport.cs
index 04aa324..aa4f515 100644
--- a/MarkupString.Ansi/Emitters/AnsiEmitterSupport.cs
+++ b/MarkupString.Ansi/Emitters/AnsiEmitterSupport.cs
@@ -197,10 +197,10 @@ internal static void WriteWrapped(
 	/// Writes the body as the link the style carries, in whichever form <paramref name="features"/> allows: a
 	/// navigable URL inside an OSC 8 hyperlink, a command as an MSLP link (<c>ESC ] 68 ; 1 ; SEND ; command BEL</c>
 	/// before the text, which MSLP delimits with underline). Anything else — no link, a form the client does not
-	/// read, a URL with a scheme <see cref="UrlSafety.IsSafeNavigableUrl"/> rejects, a command holding a control
+	/// read, a URL the registry's <see cref="MarkupRegistry.Links"/> rejects, a command holding a control
 	/// character that would end the sequence early — is written as plain text.
 	/// </summary>
-	internal static void WriteLinked(in AnsiStyle style, ReadOnlySpan<char> body, TerminalFeatures features, IBufferWriter<char> output)
+	internal static void WriteLinked(in AnsiStyle style, ReadOnlySpan<char> body, TerminalFeatures features, IUrlPolicy links, IBufferWriter<char> output)
 	{
 		if (style.LinkUrl is not { Length: > 0 } target)
 		{
@@ -208,7 +208,7 @@ internal static void WriteLinked(in AnsiStyle style, ReadOnlySpan<char> body, Te
 			return;
 		}
 
-		if (style.LinkKind == LinkKind.Url && (features & TerminalFeatures.Hyperlinks) != 0 && UrlSafety.IsSafeNavigableUrl(target))
+		if (style.LinkKind == LinkKind.Url && (features & TerminalFeatures.Hyperlinks) != 0 && links.IsAllowed(target))
 		{
 			output.Write(Osc8);
 			output.Write(target);
@@ -265,7 +265,7 @@ internal static void EmitTagged(
 			{
 				var shown = style.AtDepth(colorDepth);
 				SgrWriter.Transition(AnsiStyle.None, shown, segmentOutput);
-				WriteTaggedLink(shown, segment, segmentOutput, flavour);
+				WriteTaggedLink(shown, segment, segmentOutput, flavour, segmentContext.Registry.Links);
 				if (LeavesState(shown)) SgrWriter.Reset(segmentOutput);
 			});
 	}
@@ -284,7 +284,8 @@ private static void WriteTaggedLink(
 		in AnsiStyle style,
 		ReadOnlySpan<char> body,
 		IBufferWriter<char> output,
-		TagFlavour flavour)
+		TagFlavour flavour,
+		IUrlPolicy links)
 	{
 		if (style.LinkUrl is not { Length: > 0 } url)
 		{
@@ -313,7 +314,7 @@ private static void WriteTaggedLink(
 			return;
 		}
 
-		if (!UrlSafety.IsSafeNavigableUrl(url))
+		if (!links.IsAllowed(url))
 		{
 			output.Write(body);
 			return;
diff --git a/MarkupString.Ansi/Emitters/AnsiHtmlEmitter.cs b/MarkupString.Ansi/Emitters/AnsiHtmlEmitter.cs
index e932af9..d193120 100644
--- a/MarkupString.Ansi/Emitters/AnsiHtmlEmitter.cs
+++ b/MarkupString.Ansi/Emitters/AnsiHtmlEmitter.cs
@@ -45,7 +45,7 @@ private static void WriteSpan(in AnsiStyle style, ReadOnlySpan<char> body, in Em
 
 		if (!hasStyle && !hasClasses)
 		{
-			WriteAnchored(style, body, output);
+			WriteAnchored(style, body, context.Registry.Links, output);
 			return;
 		}
 
@@ -76,7 +76,7 @@ private static void WriteSpan(in AnsiStyle style, ReadOnlySpan<char> body, in Em
 		}
 
 		output.Write(">");
-		WriteAnchored(style, body, output);
+		WriteAnchored(style, body, context.Registry.Links, output);
 		output.Write("</span>");
 	}
 
@@ -144,7 +144,7 @@ private static void AppendClass(bool on, string name, ref bool first, IBufferWri
 	/// <c>xch_cmd</c> — so it carries <c>role</c> and <c>tabindex</c> to stay keyboard-reachable. A
 	/// URL link with a scheme <see cref="UrlSafety"/> rejects falls back to plain text.
 	/// </summary>
-	private static void WriteAnchored(in AnsiStyle style, ReadOnlySpan<char> body, IBufferWriter<char> output)
+	private static void WriteAnchored(in AnsiStyle style, ReadOnlySpan<char> body, IUrlPolicy links, IBufferWriter<char> output)
 	{
 		if (style.LinkUrl is not { Length: > 0 } url)
 		{
@@ -158,7 +158,7 @@ private static void WriteAnchored(in AnsiStyle style, ReadOnlySpan<char> body, I
 			output.Write(WebUtility.HtmlEncode(url));
 			output.Write("\"");
 		}
-		else if (UrlSafety.IsSafeNavigableUrl(url))
+		else if (links.IsAllowed(url))
 		{
 			output.Write("<a href=\"");
 			output.Write(WebUtility.HtmlEncode(url));
diff --git a/MarkupString.Ansi/Emitters/AnsiMarkdownEmitter.cs b/MarkupString.Ansi/Emitters/AnsiMarkdownEmitter.cs
index 8457005..0ab6013 100644
--- a/MarkupString.Ansi/Emitters/AnsiMarkdownEmitter.cs
+++ b/MarkupString.Ansi/Emitters/AnsiMarkdownEmitter.cs
@@ -35,7 +35,7 @@ public bool TryEmit(MarkupSet set, ReadOnlySpan<char> body, in EmitContext conte
 			return true;
 		}
 
-		var own = Delimiters(AnsiEmitterSupport.Fold(set, context.Format));
+		var own = Delimiters(AnsiEmitterSupport.Fold(set, context.Format), context.Registry.Links);
 		WriteDelimited(own, Shared(own, context.Previous, context), Shared(own, context.Next, context), body, output);
 		return true;
 	}
@@ -51,12 +51,12 @@ public bool TryEmit(MarkupSet set, ReadOnlySpan<char> body, in EmitContext conte
 	/// The delimiters <paramref name="style"/> is written with, outermost first, always in the same order —
 	/// a link, then strikethrough, bold and italic — so two runs that share some of them share the outermost.
 	/// </summary>
-	private static List<Delimiter> Delimiters(in AnsiStyle style)
+	private static List<Delimiter> Delimiters(in AnsiStyle style, IUrlPolicy links)
 	{
 		var delimiters = new List<Delimiter>(4);
 		if (style.LinkKind == LinkKind.Url
 			&& style.LinkUrl is { Length: > 0 } url
-			&& UrlSafety.IsSafeNavigableUrl(url))
+			&& links.IsAllowed(url))
 			delimiters.Add(new Delimiter("[", "](" + MarkdownSyntax.Destination(url) + ")"));
 		if (style.StrikeThrough) delimiters.Add(Strike);
 		if (style.Bold) delimiters.Add(Strong);
@@ -80,14 +80,14 @@ private static bool StandsAlone(MarkupSet markups, in EmitContext context)
 	private static int Shared(List<Delimiter> own, MarkupSet? neighbour, in EmitContext context)
 	{
 		if (own.Count == 0 || neighbour is null || StandsAlone(neighbour, context)) return 0;
-		var theirs = Delimiters(AnsiEmitterSupport.Fold(neighbour, context.Format));
+		var theirs = Delimiters(AnsiEmitterSupport.Fold(neighbour, context.Format), context.Registry.Links);
 		var shared = 0;
 		while (shared < own.Count && shared < theirs.Count && own[shared] == theirs[shared]) shared++;
 		return shared;
 	}
 
 	private static void WriteAlone(in AnsiStyle style, ReadOnlySpan<char> body, in EmitContext context, IBufferWriter<char> output) =>
-		WriteDelimited(Delimiters(style), 0, 0, body, output);
+		WriteDelimited(Delimiters(style, context.Registry.Links), 0, 0, body, output);
 
 	/// <summary>
 	/// Writes <paramref name="body"/> inside <paramref name="delimiters"/>, the first <paramref name="opened"/> of
diff --git a/MarkupString.Ansi/Emitters/AnsiSetEmitter.cs b/MarkupString.Ansi/Emitters/AnsiSetEmitter.cs
index edaf826..6bd9edb 100644
--- a/MarkupString.Ansi/Emitters/AnsiSetEmitter.cs
+++ b/MarkupString.Ansi/Emitters/AnsiSetEmitter.cs
@@ -61,7 +61,7 @@ public bool TryEmit(MarkupSet set, ReadOnlySpan<char> body, in EmitContext conte
 		}
 		else
 		{
-			AnsiEmitterSupport.WriteLinked(effective, body, _options.Features, core);
+			AnsiEmitterSupport.WriteLinked(effective, body, _options.Features, context.Registry.Links, core);
 		}
 
 		// Nothing follows that would diff this state away, so close it here rather than leaving the
diff --git a/MarkupString.Extensions.DependencyInjection/MarkupString.Extensions.DependencyInjection.csproj b/MarkupString.Extensions.DependencyInjection/MarkupString.Extensions.DependencyInjection.csproj
index 4e89dae..da44efb 100644
--- a/MarkupString.Extensions.DependencyInjection/MarkupString.Extensions.DependencyInjection.csproj
+++ b/MarkupString.Extensions.DependencyInjection/MarkupString.Extensions.DependencyInjection.csproj
@@ -15,6 +15,7 @@
     <PackageReference Include="MinVer" Version="8.0.0" PrivateAssets="all" />
     <PackageReference Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="5.6.0" PrivateAssets="all" />
     <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.0" />
     <PackageReference Include="Microsoft.Extensions.Options" Version="10.0.0" />
     <PackageReference Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="10.0.0" />
   </ItemGroup>
diff --git a/MarkupString.Extensions.DependencyInjection/PublicAPI.Unshipped.txt b/MarkupString.Extensions.DependencyInjection/PublicAPI.Unshipped.txt
index 53f1e13..5f61081 100644
--- a/MarkupString.Extensions.DependencyInjection/PublicAPI.Unshipped.txt
+++ b/MarkupString.Extensions.DependencyInjection/PublicAPI.Unshipped.txt
@@ -18,7 +18,6 @@ MarkupString.Extensions.DependencyInjection.DisplaySettings.Output.set -> void
 MarkupString.Extensions.DependencyInjection.MarkupDecoderFactory
 MarkupString.Extensions.DependencyInjection.MarkupDecoderFactory.CreateDecoder(MarkupString.Decoding.DecoderOptions? options = null) -> MarkupString.Decoding.Decoder!
 MarkupString.Extensions.DependencyInjection.MarkupDecoderFactory.Defaults.get -> MarkupString.Decoding.DecoderOptions!
-MarkupString.Extensions.DependencyInjection.MarkupDecoderFactory.MarkupDecoderFactory(MarkupString.Decoding.DecoderRegistry! registry, MarkupString.Extensions.DependencyInjection.MarkupStringOptions! options, MarkupString.IUrlPolicy! links, System.Diagnostics.Metrics.IMeterFactory? meters = null) -> void
 MarkupString.Extensions.DependencyInjection.MarkupStringBuilder
 MarkupString.Extensions.DependencyInjection.MarkupStringBuilder.AddDecoders(System.Func<MarkupString.Decoding.DecoderRegistry!, MarkupString.Decoding.DecoderRegistry!>! configure) -> MarkupString.Extensions.DependencyInjection.MarkupStringBuilder!
 MarkupString.Extensions.DependencyInjection.MarkupStringBuilder.AddDisplay(System.Func<MarkupString.Display.DisplayRegistry!, MarkupString.Display.DisplayRegistry!>! configure) -> MarkupString.Extensions.DependencyInjection.MarkupStringBuilder!
@@ -48,3 +47,4 @@ MarkupString.Extensions.DependencyInjection.PictureSettings.PictureSettings() ->
 MarkupString.Extensions.DependencyInjection.ServiceCollectionExtensions
 static MarkupString.Extensions.DependencyInjection.ServiceCollectionExtensions.AddMarkupString(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, System.Action<MarkupString.Extensions.DependencyInjection.MarkupStringOptions!>? configure = null) -> MarkupString.Extensions.DependencyInjection.MarkupStringBuilder!
 MarkupString.Extensions.DependencyInjection.MarkupDecoderFactory.CreateDecoderFor(MarkupString.Decoding.ClientIdentity! identity) -> MarkupString.Decoding.Decoder!
+MarkupString.Extensions.DependencyInjection.MarkupDecoderFactory.MarkupDecoderFactory(MarkupString.Decoding.DecoderRegistry! registry, MarkupString.Extensions.DependencyInjection.MarkupStringOptions! options, MarkupString.IUrlPolicy! links, System.Diagnostics.Metrics.IMeterFactory? meters = null, Microsoft.Extensions.Logging.ILoggerFactory? loggers = null) -> void
diff --git a/MarkupString.Extensions.DependencyInjection/ServiceCollectionExtensions.cs b/MarkupString.Extensions.DependencyInjection/ServiceCollectionExtensions.cs
index 0d3294d..70fc5e5 100644
--- a/MarkupString.Extensions.DependencyInjection/ServiceCollectionExtensions.cs
+++ b/MarkupString.Extensions.DependencyInjection/ServiceCollectionExtensions.cs
@@ -6,6 +6,7 @@
 using MarkupString.Display;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.DependencyInjection.Extensions;
+using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
 namespace MarkupString.Extensions.DependencyInjection;
 
@@ -17,7 +18,8 @@ public static class ServiceCollectionExtensions
 	/// pictures) and an <see cref="IDecoderFactory"/> that makes each connection's decoder with the configured limits;
 	/// one <see cref="IPictureCache"/> every connection shares; the <see cref="DisplayRegistry"/> as the
 	/// <see cref="IStyleResolver"/>, with default <see cref="DisplayOptions"/>; and the <see cref="IUrlPolicy"/>.
-	/// Decode metrics go to the host's <see cref="IMeterFactory"/> when it has one. A service registered before this
+	/// Decode metrics go to the host's <see cref="IMeterFactory"/>, and what decoders drop is logged at debug level
+	/// to its <see cref="ILoggerFactory"/> (category <c>MarkupString.Decoding</c>), when it has them. A service registered before this
 	/// call is kept, so any of them can be replaced. Calling it again adds to the same setup.
 	/// </summary>
 	public static MarkupStringBuilder AddMarkupString(this IServiceCollection services, Action<MarkupStringOptions>? configure = null)
@@ -40,13 +42,15 @@ public static MarkupStringBuilder AddMarkupString(this IServiceCollection servic
 			sp.GetRequiredService<DecoderRegistry>(),
 			Options(sp),
 			sp.GetRequiredService<IUrlPolicy>(),
-			sp.GetService<IMeterFactory>()));
+			sp.GetService<IMeterFactory>(),
+			sp.GetService<ILoggerFactory>()));
 		services.TryAddSingleton<IDecoderFactory>(static sp => sp.GetRequiredService<MarkupDecoderFactory>());
 		services.TryAddSingleton(sp => setup.Display.Aggregate(
 			DisplayRegistry.Core.WithAnsi(Options(sp).Display.BoldIsBright), static (current, step) => step(current)));
 		services.TryAddSingleton<IStyleResolver>(static sp => sp.GetRequiredService<DisplayRegistry>());
 		services.TryAddSingleton(static sp => DisplayDefaults(Options(sp).Display, sp.GetRequiredService<IUrlPolicy>()));
-		services.TryAddSingleton(sp => setup.Markup.Aggregate(MarkupRegistry.Empty.WithAnsi(), static (current, step) => step(current)));
+		services.TryAddSingleton(sp => setup.Markup.Aggregate(
+			MarkupRegistry.Empty.WithAnsi().WithLinks(sp.GetRequiredService<IUrlPolicy>()), static (current, step) => step(current)));
 		return new MarkupStringBuilder(services, setup);
 	}
 
@@ -154,21 +158,24 @@ public MarkupStringBuilder BindConfiguration(string path = "MarkupString")
 
 /// <summary>
 /// Makes each connection's <see cref="Decoder"/> from the registered <see cref="DecoderRegistry"/>, with the
-/// configured limits, link policy, metrics and picture size.
+/// configured limits, link policy, metrics, logging and picture size.
 /// </summary>
-public sealed class MarkupDecoderFactory : IDecoderFactory
+public sealed partial class MarkupDecoderFactory : IDecoderFactory
 {
 	private readonly DecoderRegistry _registry;
 	private readonly long _maxPixels;
+	private readonly ILogger? _logger;
 
 	/// <summary>A factory over <paramref name="registry"/>.</summary>
-	public MarkupDecoderFactory(DecoderRegistry registry, MarkupStringOptions options, IUrlPolicy links, IMeterFactory? meters = null)
+	public MarkupDecoderFactory(DecoderRegistry registry, MarkupStringOptions options, IUrlPolicy links, IMeterFactory? meters = null,
+		ILoggerFactory? loggers = null)
 	{
 		ArgumentNullException.ThrowIfNull(registry);
 		ArgumentNullException.ThrowIfNull(options);
 		ArgumentNullException.ThrowIfNull(links);
 		_registry = registry;
 		_maxPixels = options.Pictures.MaxPixels;
+		_logger = loggers?.CreateLogger("MarkupString.Decoding");
 		var answers = ClientAnswers.Default;
 		answers = options.Decoding.AnswerCursorPosition ? answers | ClientAnswers.CursorPosition : answers & ~ClientAnswers.CursorPosition;
 		Defaults = new DecoderOptions
@@ -189,9 +196,13 @@ public Decoder CreateDecoder(DecoderOptions? options = null)
 	{
 		var decoder = _registry.CreateDecoder(options ?? Defaults);
 		if (_registry.Has(PicturesPlugin.Instance.Name)) decoder.Pictures().MaxPixels = _maxPixels;
+		if (_logger is { } logger && logger.IsEnabled(LogLevel.Debug)) decoder.Diagnostics.Dropped += (kind, count) => LogDropped(logger, kind, count);
 		return decoder;
 	}
 
+	[LoggerMessage(EventId = 1, Level = LogLevel.Debug, Message = "Decoder dropped {Count} × {Kind}")]
+	private static partial void LogDropped(ILogger logger, DecodeDrop kind, int count);
+
 	/// <summary>A decoder with the defaults, for a client that is <paramref name="identity"/>.</summary>
 	public Decoder CreateDecoderFor(ClientIdentity identity)
 	{
diff --git a/MarkupString.Html/HtmlTagPolicy.cs b/MarkupString.Html/HtmlTagPolicy.cs
index 1e82921..05a712e 100644
--- a/MarkupString.Html/HtmlTagPolicy.cs
+++ b/MarkupString.Html/HtmlTagPolicy.cs
@@ -46,13 +46,16 @@ public sealed record HtmlTagPolicy
 
 	/// <summary>
 	/// The attributes whose value this policy checks as an address: each must be one
-	/// <see cref="UrlSafety.IsSafeNavigableUrl"/> accepts, with no whitespace or control character in it.
+	/// <see cref="Links"/> accepts, with no whitespace or control character in it.
 	/// Empty by default — which addresses a client of yours may be sent to is your decision, not this
 	/// library's. <see cref="AddressAttributes"/> is the list of attributes HTML gives an address to,
 	/// if you want to check them all.
 	/// </summary>
 	public IReadOnlySet<string> UrlAttributes { get; init => field = IgnoringCase(value) ?? throw new ArgumentNullException(nameof(value)); } = FrozenSet<string>.Empty;
 
+	/// <summary>Which addresses <see cref="UrlAttributes"/> may hold. <see cref="UrlPolicy.Safe"/> unless set.</summary>
+	public IUrlPolicy Links { get; init => field = value ?? throw new ArgumentNullException(nameof(value)); } = UrlPolicy.Safe;
+
 	/// <summary>What happens to the attributes when one is not allowed.</summary>
 	public HtmlAttributeViolation OnViolation { get; init; } = HtmlAttributeViolation.DropAttribute;
 
@@ -115,6 +118,6 @@ private bool Allows(HtmlAttribute attribute) =>
 		_ => set.ToFrozenSet(StringComparer.OrdinalIgnoreCase),
 	};
 
-	private static bool IsSafeAddress(string value) =>
-		!value.Any(c => char.IsControl(c) || char.IsWhiteSpace(c)) && UrlSafety.IsSafeNavigableUrl(value);
+	private bool IsSafeAddress(string value) =>
+		!value.Any(c => char.IsControl(c) || char.IsWhiteSpace(c)) && Links.IsAllowed(value);
 }
diff --git a/MarkupString.Html/PublicAPI.Unshipped.txt b/MarkupString.Html/PublicAPI.Unshipped.txt
index 7dc5c58..ac70350 100644
--- a/MarkupString.Html/PublicAPI.Unshipped.txt
+++ b/MarkupString.Html/PublicAPI.Unshipped.txt
@@ -1 +1,3 @@
 #nullable enable
+MarkupString.Html.HtmlTagPolicy.Links.get -> MarkupString.IUrlPolicy!
+MarkupString.Html.HtmlTagPolicy.Links.init -> void
diff --git a/MarkupString.Tests/Decoding/InjectionTests.cs b/MarkupString.Tests/Decoding/InjectionTests.cs
index 13a0f4e..7783643 100644
--- a/MarkupString.Tests/Decoding/InjectionTests.cs
+++ b/MarkupString.Tests/Decoding/InjectionTests.cs
@@ -1,12 +1,16 @@
 using System.Diagnostics.CodeAnalysis;
 using System.Diagnostics.Metrics;
+using MarkupString.Ansi;
 using MarkupString.Ansi.Decoding;
 using MarkupString.Decoding;
 using MarkupString.Display;
 using MarkupString.Extensions.DependencyInjection;
+using MarkupString.Html;
+using MarkupString.Mxp;
 using MarkupString.Mxp.Decoding;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
 
 /// <summary>The seams a host injects through, and the package that wires them into a service collection.</summary>
 public class InjectionTests
@@ -121,4 +125,71 @@ public async Task AddMarkupString_TakesAPictureCacheOfYourOwn()
 		using var services = new ServiceCollection().AddMarkupString().UsePictureCache<NoCache>().Services.BuildServiceProvider();
 		await Assert.That(services.GetRequiredService<IDecoderFactory>().CreateDecoder().Pictures().Cache).IsTypeOf<NoCache>();
 	}
+
+	public static IEnumerable<Func<MarkupFormat>> LinkFormats() =>
+		[() => MarkupFormat.Ansi, () => MarkupFormat.Html, () => MarkupFormat.Mxp, () => MarkupFormat.BBCode, () => MarkupFormat.Markdown];
+
+	[Test]
+	[MethodDataSource(nameof(LinkFormats))]
+	public async Task Writers_AskTheRegistrysLinkPolicy(MarkupFormat format)
+	{
+		var link = MarkupText.Wrap(new AnsiMarkup(new AnsiStyle { LinkUrl = "mudclient://look", LinkKind = LinkKind.Url }), "look");
+		var safe = MarkupRegistry.Empty.WithAnsi().WithMxp().WithAnsiOutput(AnsiColorDepth.TrueColor);
+		var open = safe.WithLinks(UrlPolicy.WithSchemes("mudclient"));
+		await Assert.That(link.Render(format, safe)).DoesNotContain("mudclient://look");
+		await Assert.That(link.Render(format, open)).Contains("mudclient://look");
+		await Assert.That(open.WithMxp().Links).IsSameReferenceAs(open.Links);
+	}
+
+	[Test]
+	public async Task HtmlTagPolicy_AsksItsLinkPolicy()
+	{
+		var policy = HtmlTagPolicy.WellFormed with { UrlAttributes = HtmlTagPolicy.AddressAttributes };
+		await Assert.That(policy.TryCreate("a", "href=\"mudclient://look\"", out var dropped)).IsTrue();
+		await Assert.That(dropped!.Attributes).IsNull();
+		await Assert.That((policy with { Links = UrlPolicy.WithSchemes("mudclient") }).TryCreate("a", "href=\"mudclient://look\"", out var kept)).IsTrue();
+		await Assert.That(kept!.Attributes).Contains("mudclient://look");
+	}
+
+	[Test]
+	public async Task Diagnostics_RaiseDropped()
+	{
+		var decoder = VtDecoding.Terminal.CreateDecoder();
+		var dropped = new List<(DecodeDrop, int)>();
+		decoder.Diagnostics.Dropped += (kind, count) => dropped.Add((kind, count));
+		decoder.Feed("\e[5;5H\u0001");
+		await Assert.That(dropped).IsEquivalentTo([(DecodeDrop.UnhandledSequence, 1), (DecodeDrop.UnhandledControl, 1)]);
+	}
+
+	private sealed class Captured : ILoggerProvider, ILogger
+	{
+		public List<string> Lines { get; } = [];
+
+		public ILogger CreateLogger(string categoryName) => this;
+
+		public IDisposable? BeginScope<TState>(TState state) where TState : notnull => null;
+
+		public bool IsEnabled(LogLevel logLevel) => true;
+
+		public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter) =>
+			Lines.Add(formatter(state, exception));
+
+		public void Dispose()
+		{
+		}
+	}
+
+	[Test]
+	public async Task AddMarkupString_LogsWhatDecodersDrop()
+	{
+		var captured = new Captured();
+		using var services = new ServiceCollection()
+			.AddLogging(logging => logging.SetMinimumLevel(LogLevel.Debug).AddProvider(captured))
+			.AddMarkupString(options => options.LinkSchemes.Add("mudclient"))
+			.Services.BuildServiceProvider();
+		services.GetRequiredService<IDecoderFactory>().CreateDecoder().Feed("\e[5;5H");
+		await Assert.That(captured.Lines).IsEquivalentTo(["Decoder dropped 1 × UnhandledSequence"]);
+		var link = MarkupText.Wrap(new AnsiMarkup(new AnsiStyle { LinkUrl = "mudclient://look", LinkKind = LinkKind.Url }), "look");
+		await Assert.That(link.Render(MarkupFormat.Html, services.GetRequiredService<MarkupRegistry>())).Contains("href=\"mudclient://look\"");
+	}
 }
diff --git a/MarkupString.Tests/MarkupString.Tests.csproj b/MarkupString.Tests/MarkupString.Tests.csproj
index 9686a2c..1529ede 100644
--- a/MarkupString.Tests/MarkupString.Tests.csproj
+++ b/MarkupString.Tests/MarkupString.Tests.csproj
@@ -13,6 +13,7 @@
     <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
     <PackageReference Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
     <PackageReference Include="Microsoft.Extensions.Diagnostics" Version="10.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Logging" Version="10.0.0" />
     <!-- A GitHub-flavoured Markdown reader, so the Markdown tests check what a reader makes of the output
          rather than only the characters written. -->
     <PackageReference Include="Markdig" Version="1.5.1" />
diff --git a/MarkupString/Decoding/Decoder.cs b/MarkupString/Decoding/Decoder.cs
index e905b4b..0132d80 100644
--- a/MarkupString/Decoding/Decoder.cs
+++ b/MarkupString/Decoding/Decoder.cs
@@ -245,44 +245,68 @@ public DecodeDiagnostics()
 	public int AbandonedSequences
 	{
 		get => _abandoned;
-		set => _abandoned = Report(_abandoned, value, "abandoned-sequence");
+		set => _abandoned = Report(_abandoned, value, DecodeDrop.AbandonedSequence);
 	}
 
 	/// <summary>Well-formed sequences no handler claimed.</summary>
 	public int UnhandledSequences
 	{
 		get => _unhandled;
-		set => _unhandled = Report(_unhandled, value, "unhandled-sequence");
+		set => _unhandled = Report(_unhandled, value, DecodeDrop.UnhandledSequence);
 	}
 
 	/// <summary>Control characters no handler claimed.</summary>
 	public int UnhandledControls
 	{
 		get => _controls;
-		set => _controls = Report(_controls, value, "unhandled-control");
+		set => _controls = Report(_controls, value, DecodeDrop.UnhandledControl);
 	}
 
 	/// <summary>Things dropped because a limit was reached: an element stack, a line length, a picture size.</summary>
 	public int LimitsReached
 	{
 		get => _limits;
-		set => _limits = Report(_limits, value, "limit");
+		set => _limits = Report(_limits, value, DecodeDrop.Limit);
 	}
 
 	/// <summary>Pictures that could not be decoded.</summary>
 	public int PicturesFailed
 	{
 		get => _pictures;
-		set => _pictures = Report(_pictures, value, "picture");
+		set => _pictures = Report(_pictures, value, DecodeDrop.Picture);
 	}
 
-	private int Report(int before, int after, string kind)
+	/// <summary>Raised each time a count goes up, with what was dropped and how many.</summary>
+	public event Action<DecodeDrop, int>? Dropped;
+
+	private int Report(int before, int after, DecodeDrop kind)
 	{
-		if (after > before) _metrics?.Dropped(after - before, kind);
+		if (after <= before) return after;
+		_metrics?.Dropped(after - before, kind);
+		Dropped?.Invoke(kind, after - before);
 		return after;
 	}
 }
 
+/// <summary>What a decoder dropped, as <see cref="DecodeDiagnostics.Dropped"/> reports it.</summary>
+public enum DecodeDrop
+{
+	/// <summary>A sequence that was malformed, too long, or cut off by a line ending.</summary>
+	AbandonedSequence,
+
+	/// <summary>A well-formed sequence no handler claimed.</summary>
+	UnhandledSequence,
+
+	/// <summary>A control character no handler claimed.</summary>
+	UnhandledControl,
+
+	/// <summary>Something dropped because a limit was reached.</summary>
+	Limit,
+
+	/// <summary>A picture that could not be decoded.</summary>
+	Picture,
+}
+
 /// <summary>The decoding meter, one for each meter factory.</summary>
 internal sealed class DecodeMetrics
 {
@@ -299,5 +323,14 @@ private DecodeMetrics(System.Diagnostics.Metrics.Meter meter) =>
 	public static DecodeMetrics For(System.Diagnostics.Metrics.IMeterFactory? factory) =>
 		factory is null ? Shared : ByFactory.GetValue(factory, static f => new DecodeMetrics(f.Create(new System.Diagnostics.Metrics.MeterOptions(MeterName))));
 
-	public void Dropped(int count, string kind) => _dropped.Add(count, new KeyValuePair<string, object?>("kind", kind));
+	public void Dropped(int count, DecodeDrop kind) => _dropped.Add(count, new KeyValuePair<string, object?>("kind", Tag(kind)));
+
+	private static string Tag(DecodeDrop kind) => kind switch
+	{
+		DecodeDrop.AbandonedSequence => "abandoned-sequence",
+		DecodeDrop.UnhandledSequence => "unhandled-sequence",
+		DecodeDrop.UnhandledControl => "unhandled-control",
+		DecodeDrop.Limit => "limit",
+		_ => "picture",
+	};
 }
diff --git a/MarkupString/MarkupRegistry.cs b/MarkupString/MarkupRegistry.cs
index 9402899..329e5a4 100644
--- a/MarkupString/MarkupRegistry.cs
+++ b/MarkupString/MarkupRegistry.cs
@@ -41,6 +41,19 @@ private MarkupRegistry(
 		_blockEmitters = blockEmitters;
 	}
 
+	/// <summary>
+	/// Which link addresses the emitters write as links; one that may not is written as its text. Every emitter in
+	/// this package asks it. <see cref="UrlPolicy.Safe"/> unless set with <see cref="WithLinks"/>.
+	/// </summary>
+	public IUrlPolicy Links { get; private init; } = UrlPolicy.Safe;
+
+	/// <summary>The registry with links decided by <paramref name="links"/>.</summary>
+	public MarkupRegistry WithLinks(IUrlPolicy links)
+	{
+		ArgumentNullException.ThrowIfNull(links);
+		return new MarkupRegistry(_emitters, _setEmitters, _framers, _lineFramers, _codecsByKind, _codecsByType, _blockEmitters, _blockCodecsByKind, _blockCodecsByType) { Links = links };
+	}
+
 	/// <summary>A registry that knows nothing: every markup passes its body through unchanged.</summary>
 	public static readonly MarkupRegistry Empty = new(
 		FrozenDictionary<(Type, MarkupFormat), IMarkupEmitter>.Empty,
@@ -102,7 +115,7 @@ public MarkupRegistry With(IMarkupEmitter emitter)
 		var emitters = new Dictionary<(Type, MarkupFormat), IMarkupEmitter>(_emitters.Count + 1);
 		foreach (var pair in _emitters) emitters[pair.Key] = pair.Value;
 		emitters[(emitter.MarkupType, emitter.Format)] = emitter;
-		return new MarkupRegistry(emitters.ToFrozenDictionary(), _setEmitters, _framers, _lineFramers, _codecsByKind, _codecsByType, _blockEmitters, _blockCodecsByKind, _blockCodecsByType);
+		return new MarkupRegistry(emitters.ToFrozenDictionary(), _setEmitters, _framers, _lineFramers, _codecsByKind, _codecsByType, _blockEmitters, _blockCodecsByKind, _blockCodecsByType) { Links = Links };
 	}
 
 	/// <summary>Returns a registry with <paramref name="emitter"/> added, replacing any set emitter for the same format.</summary>
@@ -112,7 +125,7 @@ public MarkupRegistry With(IMarkupSetEmitter emitter)
 		var setEmitters = new Dictionary<MarkupFormat, IMarkupSetEmitter>(_setEmitters.Count + 1);
 		foreach (var pair in _setEmitters) setEmitters[pair.Key] = pair.Value;
 		setEmitters[emitter.Format] = emitter;
-		return new MarkupRegistry(_emitters, setEmitters.ToFrozenDictionary(), _framers, _lineFramers, _codecsByKind, _codecsByType, _blockEmitters, _blockCodecsByKind, _blockCodecsByType);
+		return new MarkupRegistry(_emitters, setEmitters.ToFrozenDictionary(), _framers, _lineFramers, _codecsByKind, _codecsByType, _blockEmitters, _blockCodecsByKind, _blockCodecsByType) { Links = Links };
 	}
 
 	/// <summary>Returns a registry with <paramref name="framer"/> added, replacing any framer for the same format.</summary>
@@ -122,7 +135,7 @@ public MarkupRegistry With(IFormatFramer framer)
 		var framers = new Dictionary<MarkupFormat, IFormatFramer>(_framers.Count + 1);
 		foreach (var pair in _framers) framers[pair.Key] = pair.Value;
 		framers[framer.Format] = framer;
-		return new MarkupRegistry(_emitters, _setEmitters, framers.ToFrozenDictionary(), _lineFramers, _codecsByKind, _codecsByType, _blockEmitters, _blockCodecsByKind, _blockCodecsByType);
+		return new MarkupRegistry(_emitters, _setEmitters, framers.ToFrozenDictionary(), _lineFramers, _codecsByKind, _codecsByType, _blockEmitters, _blockCodecsByKind, _blockCodecsByType) { Links = Links };
 	}
 
 	/// <summary>Returns a registry with <paramref name="framer"/> added, replacing any line framer for the same format.</summary>
@@ -132,7 +145,7 @@ public MarkupRegistry With(ILineFramer framer)
 		var lineFramers = new Dictionary<MarkupFormat, ILineFramer>(_lineFramers.Count + 1);
 		foreach (var pair in _lineFramers) lineFramers[pair.Key] = pair.Value;
 		lineFramers[framer.Format] = framer;
-		return new MarkupRegistry(_emitters, _setEmitters, _framers, lineFramers.ToFrozenDictionary(), _codecsByKind, _codecsByType, _blockEmitters, _blockCodecsByKind, _blockCodecsByType);
+		return new MarkupRegistry(_emitters, _setEmitters, _framers, lineFramers.ToFrozenDictionary(), _codecsByKind, _codecsByType, _blockEmitters, _blockCodecsByKind, _blockCodecsByType) { Links = Links };
 	}
 
 	/// <summary>
@@ -162,7 +175,7 @@ public MarkupRegistry With(IMarkupCodec codec)
 		foreach (var pair in _codecsByType)
 			if (!string.Equals(pair.Value.Kind, codec.Kind, StringComparison.Ordinal)) byType[pair.Key] = pair.Value;
 		byType[codec.MarkupType] = codec;
-		return new MarkupRegistry(_emitters, _setEmitters, _framers, _lineFramers, byKind.ToFrozenDictionary(StringComparer.Ordinal), byType.ToFrozenDictionary(), _blockEmitters, _blockCodecsByKind, _blockCodecsByType);
+		return new MarkupRegistry(_emitters, _setEmitters, _framers, _lineFramers, byKind.ToFrozenDictionary(StringComparer.Ordinal), byType.ToFrozenDictionary(), _blockEmitters, _blockCodecsByKind, _blockCodecsByType) { Links = Links };
 	}
 
 	/// <summary>
@@ -177,7 +190,7 @@ public MarkupRegistry With(IBlockEmitter emitter)
 		var emitters = new Dictionary<(Type, MarkupFormat), IBlockEmitter>(_blockEmitters.Count + 1);
 		foreach (var pair in _blockEmitters) emitters[pair.Key] = pair.Value;
 		emitters[(emitter.MarkupType, emitter.Format)] = emitter;
-		return new MarkupRegistry(_emitters, _setEmitters, _framers, _lineFramers, _codecsByKind, _codecsByType, emitters.ToFrozenDictionary(), _blockCodecsByKind, _blockCodecsByType);
+		return new MarkupRegistry(_emitters, _setEmitters, _framers, _lineFramers, _codecsByKind, _codecsByType, emitters.ToFrozenDictionary(), _blockCodecsByKind, _blockCodecsByType) { Links = Links };
 	}
 
 	/// <summary>The block emitter for <paramref name="markupType"/> in <paramref name="format"/>, or null.</summary>
@@ -239,7 +252,8 @@ public MarkupRegistry With(Layout.BlockCodec codec)
 			if (!string.Equals(pair.Value.Kind, codec.Kind, StringComparison.Ordinal)) byType[pair.Key] = pair.Value;
 		byType[codec.BlockType] = codec;
 		return new MarkupRegistry(_emitters, _setEmitters, _framers, _lineFramers, _codecsByKind, _codecsByType, _blockEmitters,
-			byKind.ToFrozenDictionary(StringComparer.Ordinal), byType.ToFrozenDictionary());
+			byKind.ToFrozenDictionary(StringComparer.Ordinal), byType.ToFrozenDictionary())
+		{ Links = Links };
 	}
 
 	/// <summary>The block codec registered for <paramref name="kind"/>, or <see langword="null"/>.</summary>
diff --git a/MarkupString/PublicAPI.Unshipped.txt b/MarkupString/PublicAPI.Unshipped.txt
index b3965c1..de9ef4b 100644
--- a/MarkupString/PublicAPI.Unshipped.txt
+++ b/MarkupString/PublicAPI.Unshipped.txt
@@ -756,3 +756,12 @@ static MarkupString.Display.CellRenderer.Layout(MarkupString.MarkupText! text, i
 static MarkupString.Display.SpanRenderer.Render(MarkupString.MarkupText! text, MarkupString.Display.IStyleResolver! registry, MarkupString.Display.DisplayOptions! options) -> System.Collections.Generic.IReadOnlyList<MarkupString.Display.DisplaySpan>!
 static MarkupString.UrlPolicy.Safe.get -> MarkupString.UrlPolicy!
 static MarkupString.UrlPolicy.WithSchemes(params System.Collections.Generic.IEnumerable<string!>! schemes) -> MarkupString.UrlPolicy!
+MarkupString.MarkupRegistry.Links.get -> MarkupString.IUrlPolicy!
+MarkupString.MarkupRegistry.WithLinks(MarkupString.IUrlPolicy! links) -> MarkupString.MarkupRegistry!
+MarkupString.Decoding.DecodeDiagnostics.Dropped -> System.Action<MarkupString.Decoding.DecodeDrop, int>?
+MarkupString.Decoding.DecodeDrop
+MarkupString.Decoding.DecodeDrop.AbandonedSequence = 0 -> MarkupString.Decoding.DecodeDrop
+MarkupString.Decoding.DecodeDrop.Limit = 3 -> MarkupString.Decoding.DecodeDrop
+MarkupString.Decoding.DecodeDrop.Picture = 4 -> MarkupString.Decoding.DecodeDrop
+MarkupString.Decoding.DecodeDrop.UnhandledControl = 2 -> MarkupString.Decoding.DecodeDrop
+MarkupString.Decoding.DecodeDrop.UnhandledSequence = 1 -> MarkupString.Decoding.DecodeDrop
diff --git a/docs/decoding.md b/docs/decoding.md
index 431f9a7..d7b08a1 100644
--- a/docs/decoding.md
+++ b/docs/decoding.md
@@ -177,7 +177,7 @@ Decoder.DecodeAll("\e(0lqqk\e(B ok", registry)[0].Content;  // ┌──┐ ok
 | `10`, `11`, `12` | Set the foreground, background, cursor colour, or answer `?` (10 and 11 only). `10;a;b` sets 10 and 11 at once. |
 | `110`, `111`, `112` | Reset them |
 | `52;sel;base64` | `ClipboardEvent` with the decoded text, or a null text for `?`. Invalid base64 is dropped. |
-| `8;params;uri` | A link over the text that follows, until an empty uri. An address longer than 2083 characters, or one `UrlSafety.IsSafeNavigableUrl` refuses (`javascript:` and the like), ends the link instead. The address must pass `DecoderOptions.Links` (`UrlPolicy.Safe` unless set). An `id=` among the params becomes a `LinkGroupMarkup`, and so `Interaction.Group`: the text under it is one link even across lines. |
+| `8;params;uri` | A link over the text that follows, until an empty uri. An address longer than 2083 characters, or one `DecoderOptions.Links` refuses (`UrlPolicy.Safe` unless set, which refuses `javascript:` and the like), ends the link instead. An `id=` among the params becomes a `LinkGroupMarkup`, and so `Interaction.Group`: the text under it is one link even across lines. |
 | `68;1;SEND;command` | An MSLP command link over the underlined text that follows. Turning the underline off ends it, and so does the end of the line. |
 
 Colours are X11 specs: `rgb:r/g/b` with one to four hex digits a channel, or `#rgb`, `#rrggbb`,
@@ -582,7 +582,7 @@ What the tags become:
 | Tag | Markup |
 |---|---|
 | `B`, `I`, `U`, `S`, `H`, `COLOR`, `FONT` | An `AnsiMarkup`. SGR inside an MXP colour wins, as in an MXP client. |
-| `A href hint` | A URL link, when `UrlSafety` allows the address |
+| `A href hint` | A URL link, when `DecoderOptions.Links` allows the address |
 | `SEND href hint prompt` | A command link. With several commands (`a\|b`) or `PROMPT`, a `CommandMenuMarkup` as well. With no `href`, or `&text;` in it, the command is the tag's text. |
 | `IMAGE fname url w h align` | An `ImageMarkup`. Sized in cells (`W=4c H=2c`), it is drawn over the cells the server leaves for it. |
 | `SOUND`, `MUSIC` | `SoundMarkup` or `SoundStopMarkup` points |
diff --git a/docs/dependency-injection.md b/docs/dependency-injection.md
index bb70fef..b0295ab 100644
--- a/docs/dependency-injection.md
+++ b/docs/dependency-injection.md
@@ -31,7 +31,7 @@ your own first replaces it.
 
 | Service | What it is |
 |---|---|
-| `MarkupRegistry` | `MarkupRegistry.Empty.WithAnsi()` and each `AddMarkup` step |
+| `MarkupRegistry` | `MarkupRegistry.Empty.WithAnsi().WithLinks(policy)` and each `AddMarkup` step |
 | `DecoderRegistry` | `WithVt()`, `WithPictures(cache)` unless pictures are off, and each `AddDecoders` step |
 | `MarkupDecoderFactory`, `IDecoderFactory` | Makes a decoder per connection with the configured limits, link policy, metrics and picture size |
 | `IPictureCache` | One `MemoryPictureCache` that every connection shares |
@@ -70,15 +70,22 @@ These are in the core packages and need no container.
   and `CellRenderer` take one.
 - `IUrlPolicy`: which link addresses are allowed. `UrlPolicy.Safe` is the default;
   `UrlPolicy.WithSchemes("mudclient")` adds schemes, never `javascript`, `data`, `vbscript` or `file`.
-  Set it as `DecoderOptions.Links` (what a server's links become) and `DisplayOptions.Links` (what is
-  drawn as clickable). The writers still use `UrlSafety`.
+  Set it as `DecoderOptions.Links` (what a server's links become), `DisplayOptions.Links` (what is
+  drawn as clickable), `MarkupRegistry.WithLinks` (what every writer, ANSI, HTML, MXP, Pueblo, BBCode
+  and Markdown, writes as a link) and `HtmlTagPolicy.Links` (which addresses a checked tag may hold).
+  `AddMarkupString` sets the first three to the registered policy.
 - `IPictureCache`: where decoded pictures are kept; `WithPictures(cache)` shares one.
 - `IColorResolver`: how palette colours become RGB, as `DisplayOptions.Colors`.
 
-## Metrics
+## Metrics and logging
 
 Each decoder reports what it drops on the `MarkupString.Decoding` meter, as the counter
 `markupstring.decoding.dropped` with a `kind` tag: `abandoned-sequence`, `unhandled-sequence`,
 `unhandled-control`, `limit` or `picture`. With `DecoderOptions.Meters` (the factory sets it to the
 host's `IMeterFactory` when one is registered) the meter comes from that factory, so
 `dotnet-counters` and OpenTelemetry see it with the host's other meters.
+
+`decoder.Diagnostics.Dropped` is raised with a `DecodeDrop` and a count each time one goes up. When the
+host registers an `ILoggerFactory`, the factory logs each one at `Debug` under the category
+`MarkupString.Decoding` (event 1, `Decoder dropped {Count} × {Kind}`); it subscribes only when that
+level is on, so a quiet host pays nothing.
diff --git a/docs/formats.md b/docs/formats.md
index cfffcc5..a677d22 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -204,7 +204,7 @@ line.Render(MarkupFormat.Markdown);  // **Note:** see [the rules](https://exampl
   opened again round a line ending, since emphasis cannot cross a blank line. Markdown itself does not
   read a delimiter between punctuation and a letter, as in `**Note:**text`; leave a space there.
 - **Links**: a URL link is `[text](address)`, its address percent-encoded where Markdown would end it
-  early (a space, parentheses, angle brackets, a backslash, a pipe); an address `UrlSafety` refuses, and a
+  early (a space, parentheses, angle brackets, a backslash, a pipe); an address the registry's `Links` refuses, and a
   command link, are their text. A picture is `![description](address)` when its address is http(s) or
   relative, and its text otherwise; a picture inside a link is a linked image. Points — sounds, a bell, a
   clear — write nothing, and the rest of the shared vocabulary writes its text.
@@ -303,7 +303,7 @@ text.Render(MarkupFormat.Mxp);                            // <SEND HREF="north">
 
 `HtmlMarkup.Create` writes its tag name and attribute string as given. `HtmlTagPolicy` is the machinery
 for holding one to a list of allowed tags and attributes, with any address-bearing attribute checked
-against `UrlSafety`; `WithHtml(policy)` applies it to every tag rendered in `Html` as it is written, so
+against the policy's `Links` (`UrlPolicy.Safe` unless set); `WithHtml(policy)` applies it to every tag rendered in `Html` as it is written, so
 a refused tag leaves its body unwrapped and a refused attribute is dropped.
 
 The library ships no posture of its own — `HtmlTagPolicy.WellFormed` allows any well-formed tag, and

From 5a6d0ae6d5dc7eeac9c28d82a0be2ebb2bdf8797 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Nov 2026 23:36:40 +0000
Subject: [PATCH 19/19] Release 2.26.0 in the changelog

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rqqt7WGskvSsoRXvKMqybx
---
 CHANGELOG.md          | 6 +++---
 Directory.Build.props | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8ece7bb..bb7d12a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,12 +1,12 @@
 # Changelog
 
-All notable changes to `MarkupString`, `MarkupString.Ansi`, `MarkupString.Html`, `MarkupString.Mxp`
-and `MarkupString.Pueblo`. The packages share one version and are released together.
+All notable changes to `MarkupString`, `MarkupString.Ansi`, `MarkupString.Html`, `MarkupString.Mxp`,
+`MarkupString.Pueblo` and `MarkupString.Extensions.DependencyInjection`. The packages share one version and are released together.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
 follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased
+## 2.26.0 — 2026-11-06
 
 ### Added
 
diff --git a/Directory.Build.props b/Directory.Build.props
index 2ad814a..8740ba5 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -23,7 +23,7 @@
   </PropertyGroup>
 
   <!--
-    Package metadata that is identical across the five shipping packages. Everything that
+    Package metadata that is identical across the shipping packages. Everything that
     differs per package — PackageId, AssemblyName, Description, project references — stays in
     the project file. Test and smoke projects set IsPackable=false, so these are inert there.
   -->