Add MarkupString.Pueblo: Pueblo's own extensions

CHANGELOG.md

@@ -10,6 +10,43 @@ follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **`MarkupString.Pueblo`, a new package: Pueblo's own extensions.** `PuebloElements` builds the
+  `xch_` vocabulary a Pueblo client reads — `xch_pane`, `xch_page`, `xch_prefetch`, `xch_mudtext`, the
+  `xch_sound`/`xch_alert`/`xch_speech` family, the `xch_mode` switches, and an `<img>` carrying
+  `xch_cmd`, `xch_hint` or `xch_graph` — from the client's own tag and attribute tables. They render as
+  Pueblo tags for `Pueblo`, as an image or a span for `Html` where one fits, and as nothing at all
+  everywhere else, carrier included.
+  - Plain HTML stays `HtmlMarkup`'s (Pueblo reads an HTML subset), and styling and links stay
+    `AnsiMarkup`'s, which already writes each dialect's own form. Only what is Pueblo's alone is here,
+    so nothing about the existing kinds changes.
+
+- **`MarkupString.Mxp`, a new package: MXP's own elements.** `MxpElements` builds what the
+  specification defines — `SOUND`, `MUSIC`, `IMAGE`, `GAUGE`, `STAT`, `FRAME`, `VAR`, `EXPIRE`,
+  `RELOCATE`, `USER`, `PASSWORD`, `NOBR`, `SBR` — and `MxpElement` writes one it does not. They render
+  as MXP tags for `Mxp`, as the nearest thing a browser has for `Html` (an `<img>`, an `<audio>`, a
+  `data-entity` span a page can draw), and as **nothing at all** for every other format, the zero-width
+  carrier a standalone element rides on included, so the same text is safe to send to every client.
+  - An address is written for a browser only when the element carries an absolute `http`/`https` URL of
+    its own: MXP's `FName` names a file in the game's sound or image directory, which a browser cannot
+    resolve.
+  - `WithMxp(element => ...)` holds what is written to what the client answered in MXP's `<SUPPORT>`
+    exchange; a refused element writes nothing, or its content alone when it wraps, so a `FRAME` a client
+    cannot open does not take the text inside it. With no predicate every element is written — never
+    asked is not refused. `new MxpSilentEmitter(MarkupFormat.Html)` after it keeps MXP out of the browser
+    entirely.
+
+### Added
+
+- **`MarkupString.Pueblo`, a new package: Pueblo's own extensions.** `PuebloElements` builds the
+  `xch_` vocabulary a Pueblo client reads — `xch_pane`, `xch_page`, `xch_prefetch`, `xch_mudtext`, the
+  `xch_sound`/`xch_alert`/`xch_speech` family, the `xch_mode` switches, and an `<img>` carrying
+  `xch_cmd`, `xch_hint` or `xch_graph` — from the client's own tag and attribute tables. They render as
+  Pueblo tags for `Pueblo`, as an image or a span for `Html` where one fits, and as nothing at all
+  everywhere else, carrier included.
+  - Plain HTML stays `HtmlMarkup`'s (Pueblo reads an HTML subset), and styling and links stay
+    `AnsiMarkup`'s, which already writes each dialect's own form. Only what is Pueblo's alone is here,
+    so nothing about the existing kinds changes.
+
 - **Checked `HtmlMarkup` construction.** `HtmlMarkup.Tag(name, params attributes)` validates the
   tag and attribute names and writes each value encoded, so nothing in a value can end the attribute
   or the tag. `HtmlMarkup.IsValidTagName`, `IsValidAttributeName` and `TryParseAttributes` (which
@@ -44,6 +81,16 @@ follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **`MarkupString.Pueblo`, a new package: Pueblo's own extensions.** `PuebloElements` builds the
+  `xch_` vocabulary a Pueblo client reads — `xch_pane`, `xch_page`, `xch_prefetch`, `xch_mudtext`, the
+  `xch_sound`/`xch_alert`/`xch_speech` family, the `xch_mode` switches, and an `<img>` carrying
+  `xch_cmd`, `xch_hint` or `xch_graph` — from the client's own tag and attribute tables. They render as
+  Pueblo tags for `Pueblo`, as an image or a span for `Html` where one fits, and as nothing at all
+  everywhere else, carrier included.
+  - Plain HTML stays `HtmlMarkup`'s (Pueblo reads an HTML subset), and styling and links stay
+    `AnsiMarkup`'s, which already writes each dialect's own form. Only what is Pueblo's alone is here,
+    so nothing about the existing kinds changes.
+
 - `MarkupText.GraphemeCount`, lazy `EnumerateGraphemes()`, and `SubstringGraphemes(start[, count])`
   preserve all markup layers while counting and extracting whole extended grapheme clusters.
 - Allocation-free `Graphemes.Count` and `Graphemes.Enumerate` expose cluster counts and UTF-16 ranges.
@@ -74,6 +121,16 @@ follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **`MarkupString.Pueblo`, a new package: Pueblo's own extensions.** `PuebloElements` builds the
+  `xch_` vocabulary a Pueblo client reads — `xch_pane`, `xch_page`, `xch_prefetch`, `xch_mudtext`, the
+  `xch_sound`/`xch_alert`/`xch_speech` family, the `xch_mode` switches, and an `<img>` carrying
+  `xch_cmd`, `xch_hint` or `xch_graph` — from the client's own tag and attribute tables. They render as
+  Pueblo tags for `Pueblo`, as an image or a span for `Html` where one fits, and as nothing at all
+  everywhere else, carrier included.
+  - Plain HTML stays `HtmlMarkup`'s (Pueblo reads an HTML subset), and styling and links stay
+    `AnsiMarkup`'s, which already writes each dialect's own form. Only what is Pueblo's alone is here,
+    so nothing about the existing kinds changes.
+
 - A column layout engine in `MarkupString.Layout`. `ColumnFormat` describes a column — how its
   text is shaped into lines, how those lines are drawn, and how it behaves among its neighbours
   — and is composed with `with`. `MarkupText.FormatColumn` draws one; `TextLayout.Rows` and
@@ -103,6 +160,16 @@ follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **`MarkupString.Pueblo`, a new package: Pueblo's own extensions.** `PuebloElements` builds the
+  `xch_` vocabulary a Pueblo client reads — `xch_pane`, `xch_page`, `xch_prefetch`, `xch_mudtext`, the
+  `xch_sound`/`xch_alert`/`xch_speech` family, the `xch_mode` switches, and an `<img>` carrying
+  `xch_cmd`, `xch_hint` or `xch_graph` — from the client's own tag and attribute tables. They render as
+  Pueblo tags for `Pueblo`, as an image or a span for `Html` where one fits, and as nothing at all
+  everywhere else, carrier included.
+  - Plain HTML stays `HtmlMarkup`'s (Pueblo reads an HTML subset), and styling and links stay
+    `AnsiMarkup`'s, which already writes each dialect's own form. Only what is Pueblo's alone is here,
+    so nothing about the existing kinds changes.
+
 - `AnsiCss.Fixed` in `MarkupString.Ansi` — the stylesheet for the `ms-*` classes. Every one of
   those classes is written by this package's HTML emitter, so a consumer rendering HTML with
   `MarkupString` + `MarkupString.Ansi` alone can now reach the rules; in 1.0.0 they existed only in
@@ -119,6 +186,16 @@ follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **`MarkupString.Pueblo`, a new package: Pueblo's own extensions.** `PuebloElements` builds the
+  `xch_` vocabulary a Pueblo client reads — `xch_pane`, `xch_page`, `xch_prefetch`, `xch_mudtext`, the
+  `xch_sound`/`xch_alert`/`xch_speech` family, the `xch_mode` switches, and an `<img>` carrying
+  `xch_cmd`, `xch_hint` or `xch_graph` — from the client's own tag and attribute tables. They render as
+  Pueblo tags for `Pueblo`, as an image or a span for `Html` where one fits, and as nothing at all
+  everywhere else, carrier included.
+  - Plain HTML stays `HtmlMarkup`'s (Pueblo reads an HTML subset), and styling and links stay
+    `AnsiMarkup`'s, which already writes each dialect's own form. Only what is Pueblo's alone is here,
+    so nothing about the existing kinds changes.
+
 - `MarkupText` — immutable text plus coalesced, non-overlapping runs of layered markup, with
   slicing, searching, splitting, trimming, splicing, padding, centring and joining that carry the
   markup with them.

MarkupString.AotSmoke/MarkupString.AotSmoke.csproj

@@ -18,11 +18,15 @@
     <TrimmerRootAssembly Include="MarkupString" />
     <TrimmerRootAssembly Include="MarkupString.Ansi" />
     <TrimmerRootAssembly Include="MarkupString.Html" />
+    <TrimmerRootAssembly Include="MarkupString.Mxp" />
+    <TrimmerRootAssembly Include="MarkupString.Pueblo" />
   </ItemGroup>
 
   <ItemGroup>
     <ProjectReference Include="..\MarkupString\MarkupString.csproj" />
     <ProjectReference Include="..\MarkupString.Ansi\MarkupString.Ansi.csproj" />
     <ProjectReference Include="..\MarkupString.Html\MarkupString.Html.csproj" />
+    <ProjectReference Include="..\MarkupString.Mxp\MarkupString.Mxp.csproj" />
+    <ProjectReference Include="..\MarkupString.Pueblo\MarkupString.Pueblo.csproj" />
   </ItemGroup>
 </Project>

MarkupString.AotSmoke/Program.cs

@@ -2,13 +2,15 @@
 using MarkupString;
 using MarkupString.Ansi;
 using MarkupString.Html;
+using MarkupString.Mxp;
+using MarkupString.Pueblo;
 
 // 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
 // consumer touches — registry composition, nested markup, every built-in format, and the JSON
 // round trip — because those are where reflection or dynamic code would have crept in.
 
-MarkupRegistry.Default = MarkupRegistry.Empty.WithAnsi().WithHtml();
+MarkupRegistry.Default = MarkupRegistry.Empty.WithAnsi().WithHtml().WithMxp().WithPueblo();
 
 // Bold red on its own, so the plain SGR sequence appears un-merged with anything else.
 var red = MarkupText.Wrap(AnsiCodeParser.Parse("hr"), "red");
@@ -35,7 +37,14 @@
 	AnsiMarkup.Create(linkUrl: "look", linkKind: LinkKind.Command),
 	"look");
 
-var text = MarkupText.Concat([red, wide, nested, MarkupText.Space, link, MarkupText.Space, command]);
+// One of MXP's own elements: a tag in MXP, an element in HTML, and nothing anywhere else — the
+// carrier included, which is the part a trimmed build could get wrong.
+var sound = MxpElements.Sound("door.wav", volume: 80, url: "https://example.test/sounds/");
+
+// And Pueblo's own vocabulary, which the same text carries for a Pueblo client and nobody else.
+var pueblo = PuebloElements.Sound("door.wav", volume: 80);
+
+var text = MarkupText.Concat([red, wide, nested, MarkupText.Space, link, MarkupText.Space, command, sound, pueblo]);
 
 MarkupFormat[] formats =
 [

MarkupString.Html/README.md

@@ -18,6 +18,12 @@ its body untouched.
 dotnet add package MarkupString.Html
 ```
 
+It is one of MarkupString's three **tag dialects**, beside
+[`MarkupString.Mxp`](https://www.nuget.org/packages/MarkupString.Mxp) and
+[`MarkupString.Pueblo`](https://www.nuget.org/packages/MarkupString.Pueblo), which carry those two
+clients' own vocabularies. This one is HTML: what a browser reads, and what Pueblo reads as its own
+subset.
+
 ## Usage
 
 ```csharp

MarkupString.Mxp/Emitters/MxpElementEmitter.cs

@@ -0,0 +1,92 @@
+using System.Buffers;
+
+namespace MarkupString.Mxp;
+
+/// <summary>
+/// Writes an <see cref="MxpElement"/> as the MXP tag it is: <c>&lt;SOUND door.wav V=80&gt;</c> for one
+/// that stands alone, and <c>&lt;FRAME …&gt;body&lt;/FRAME&gt;</c> for one that wraps content.
+/// </summary>
+/// <remarks>
+/// The carrier a standalone element rides on is dropped rather than written: the tag stands in its
+/// place, and a zero-width space left behind would travel to clients that never asked for one.
+/// </remarks>
+public sealed class MxpElementEmitter : IMarkupEmitter
+{
+	private readonly Func<MxpElement, bool>? _supports;
+
+	/// <summary>An emitter that writes every element, for a connection whose client was never asked.</summary>
+	public static readonly MxpElementEmitter Instance = new(null);
+
+	/// <summary>
+	/// An emitter that writes only the elements <paramref name="supports"/> accepts. MXP's
+	/// <c>&lt;SUPPORT&gt;</c> exchange is what answers that question, and the answer belongs to a
+	/// connection rather than to a registry, so the predicate is the consumer's — usually a lookup into
+	/// what one client replied.
+	/// </summary>
+	/// <remarks>
+	/// An element the predicate refuses is written the way a format without MXP writes it: nothing for one
+	/// that stands alone, and the content alone for one that wraps. That second half is the point of
+	/// asking — a <c>FRAME</c> a client cannot open would otherwise take the text that followed it with
+	/// it.
+	/// </remarks>
+	public MxpElementEmitter(Func<MxpElement, bool>? supports)
+	{
+		_supports = supports;
+	}
+
+	/// <inheritdoc/>
+	public Type MarkupType => typeof(MxpElement);
+
+	/// <inheritdoc/>
+	public MarkupFormat Format => MarkupFormat.Mxp;
+
+	/// <inheritdoc/>
+	public void Emit(IMarkup markup, ReadOnlySpan<char> body, in EmitContext context, IBufferWriter<char> output)
+	{
+		ArgumentNullException.ThrowIfNull(markup);
+		ArgumentNullException.ThrowIfNull(output);
+
+		var element = (MxpElement)markup;
+		if (_supports is not null && !_supports(element))
+		{
+			if (element.WrapsContent) output.Write(body);
+			return;
+		}
+
+		output.Write(element.ToString());
+
+		if (!element.WrapsContent) return;
+
+		output.Write(body);
+		output.Write("</");
+		output.Write(element.Name);
+		output.Write(">");
+	}
+}
+
+/// <summary>
+/// Writes an <see cref="MxpElement"/> for a format that has no MXP: the body for an element that wraps
+/// content, and nothing at all for one that stands alone, carrier included.
+/// </summary>
+/// <remarks>
+/// Registered for every format this package does not translate, so the same text can go to every client:
+/// a terminal is not sent a tag it would show as text, and it is not sent the zero-width space the tag
+/// rode on either.
+/// </remarks>
+public sealed class MxpSilentEmitter(MarkupFormat format) : IMarkupEmitter
+{
+	/// <inheritdoc/>
+	public Type MarkupType => typeof(MxpElement);
+
+	/// <inheritdoc/>
+	public MarkupFormat Format { get; } = format;
+
+	/// <inheritdoc/>
+	public void Emit(IMarkup markup, ReadOnlySpan<char> body, in EmitContext context, IBufferWriter<char> output)
+	{
+		ArgumentNullException.ThrowIfNull(markup);
+		ArgumentNullException.ThrowIfNull(output);
+
+		if (((MxpElement)markup).WrapsContent) output.Write(body);
+	}
+}