Class Mml

JSON.stringify hook. Materializes with no viewer (the same viewer-less default a no-arg toString() produces). Persistence paths reach toJSON() only on already-eager strings; treat as the viewer-agnostic snapshot.

Materialize this Mml fragment to a wire string. Eager fragments return their pre-rendered markup; lazy fragments (built via Mml.compose) walk the template parts and resolve each value through renderValue(value, viewer) so per-recipient toMml implementations see the recipient.

Viewer is forward-compatible with the deferred pedagogical-seam setting and with any future per-viewer prose differentiation. v1 propagates the parameter without consulting it inside the shipped toMml implementations.

Walk the host's prototype chain via MixinApi.getAllMarkupAugmenters, fold every contributed augmenter through the text in parent-first → child-last order, return the result. Empty input short-circuits to the empty string (no point running augmenters over nothing).

Used by VisibleMixin.getMarkupLong(viewer, opts?); future host-level markup methods (getMarkupShort, scene-prose composition, etc.) use the same surface.

opts is threaded verbatim to every augmenter. Default-absent means each augmenter sees undefined and falls back to its own default behavior — the senseStripAugmenter falls back to the viewer's full sensorium.

Wrap body in <blockquote>...</blockquote> (markdown > quote).

Render a channel chip inside <chan id="...">[Label]</chan>. The id is the channel key (e.g. "gossip"); the label is what flattens out of the body when the rich render is unavailable (e.g. "[Gossip]"). The client paints the chip with the channel's stylesheet treatment; flatten emits the label verbatim.

Factory: a MentionResolver over an explicit participant set (e.g., a chat channel's tuned-in roster). The (future) chat substrate constructs the iterable at emit time; this build's tests use the factory directly with a fixture set. Same silent-on-miss contract as perceiverMentionResolver.

Wrap body in <code>...</code> (markdown `code`).

Wrap body in <color value="...">...</color> — a literal color on composed prose. The grammar is otherwise semantic (<item>, <speech> describe meaning), but a thing's color is a real property of what's perceived (visible light has color), so we name it explicitly. The value is a theme-palette token / friendly color name (purple, blue, red, grey, …) resolved client-side through the palette, so it stays legible under any theme — never a raw hex. Raw strings in the body are escaped; pass an Mml fragment to nest markup (e.g. a clickable <item> whose label is tinted).

Compose from values via tagged template. Raw strings are escaped; Mml fragments emit verbatim; objects with toMml(viewer?) get unwrapped at toString(viewer?) time — composition is lazy so a per-recipient render path threads the viewer through to value-side toMml.

Render a direction (e.g., 'north') inside <direction> tags.

Wrap body in <em>...</em> (markdown *italic* / _italic_).

Escape the five reserved characters (<, >, &, ", ') so a raw string can be embedded inside MML markup without being parsed as tag/attribute structure. Same rule Mml.compose applies to interpolated raw values; exposed publicly so other markup-producers can reuse it.

Render an actionable exit reference inside <exit dir="..." stuff-id="..."> tags. The client renderer (packages/client/src/components/MmlRenderer.tsx) turns these into clickable affordances that emit go <dir> on click.

Distinct from Mml.direction(d) — that tag is a vocabulary word (e.g., "the wind blows from the north"), not an affordance. Use Mml.exit when the displayed direction names an actual exit the actor can traverse.

Flatten an MML body to a markdown-emphasis-preserving string. Each tag is replaced by its defined failsafe form; the result round-trips through markdownToMml. Used for log capture, archive exports, and the markdown round-trip tests — distinct from stripTags, which drops emphasis entirely for the plain-mode collapse. Implementation in api/mml/flatten.ts.

Wrap a string already known to be valid MML — does NOT escape. Use for hydration, deserialization, or known-trusted programmatic assembly. Misuse = injection. Grep Mml.fromMarkup to audit.

Render an item's display name inside <item stuff-id="..."> tags. Same identity-tagging rationale as name.

Wrap a single list item in <li>...</li> (the markdown list-line payload). Distinct from <item>, which is the identity tag for game items — overloading <item> would break the renderer's per-tag treatment lookup.

Render an in-world ref clickable link. href MUST start with one of the project-defined custom URI schemes (mudcmd: for command links, mudref: for stuff-id references, mudq: for MQL query references); anything else throws. This is the server-internal compose surface — user-input link parsing (which is where unknown schemes get stripped) happens in markdownToMml, not here.

v1 wiring: command and stuff-ref schemes are clickable; mudq: is namespace-reserved but inert (the client paints it but runs no handler) — click semantics are deferred to a follow-up build.

Join a list of Mml fragments. Default behavior is "auto" — inline (English-style commas + "and") for short lists, multi-line (one indented item per line, no trailing punctuation) once the count crosses INLINE_LIST_THRESHOLD. Empty list emits nothing. Single item emits as-is.

Vertical-space discipline (see inspection-pane.md): a short list reads better inline (one wrap-line), but past ~5 items the comma-string degrades into a wall of text. The multi-line shape trades one extra newline per item for far better scannability and stops drowning the surrounding prose.

Callers that want a specific shape can pass { style: 'inline' } or { style: 'block' } to override. The new MML <list> envelope is deferred until the renderer's planned state-machine upgrade can handle nested tags; until then, style: 'block' just inserts newlines between the existing flat per-item tags — the renderer already handles plain text + flat tags side by side.

Render a location's display name inside <location stuff-id="..."> tags. Same identity-tagging rationale as name.

Parse a Discord-dialect markdown subset into MML. Handles:

• **bold** → <strong>
• *italic* / _italic_ → <em>
• `code` → <code>
• ```block``` → <pre> (verbatim; markdown inside is not parsed)
• > quote → <blockquote> (one per consecutive line run)
• - item / 1. item → <list> of <li> (one level only)
• ~~strike~~ → <strike>
• [label](URI) → <link href="URI">label</link> for whitelisted URI schemes; bare label survives if scheme is unknown
• @<word> → <mention stuff-id="X">@Word</mention> if the resolver finds a target; bare @word text survives on miss

Out of scope for v1: nested lists, GFM tables, headers, inline HTML, multi-paragraph code-block context. Code spans and code blocks are opaque — markdown emphasis inside them is preserved verbatim.

Pure on the resolver — if no resolver is passed, @<word> always leaves the literal text. Implementation in api/mml/markdown.ts.

Render an explicit @mention of a player. The stuff-id enables the renderer's viewer-relative highlight: if the mentioned stuff-id matches the viewer's own stuff-id, the mention lights up with the mention.match treatment; otherwise it gets the quieter mention.other treatment. Flatten emits the label verbatim (which is "@Name").

Produced by markdownToMml's @<word> handling when the resolver finds a target; mentions whose word doesn't resolve stay as plain @word text (the parser emits no tag).

Wrap a message body region in <msg>...</msg>. The user-content region of a chat / say / tell / emote line; carries whatever inline markdown emphasis markdownToMml produced. Accepts either an already-MML body (the common case after markdownToMml) or a raw string (escaped). The chat template (client-side) reflows this region into its content column with hanging indent.

Render an entity reference inside <name stuff-id="..."> tags. The stuff-id attribute carries the runtime identity through to the wire — server-side disambiguation walks bodies for these tokens to pick the minimal-distinguishing form per recipient, and client-side features (right-click → tell, social-graph rendering, identity overlays) read the id directly.

The inner display text is viewer-aware (see ref): it resolves through RecognitionApi.describe(viewer, stuff) per recipient, falling back to the viewer-blind baseline absent a viewer.

Render an NPC's display name inside <npc stuff-id="..."> tags. Sibling to player — same shape, but the stylesheet can give them distinct treatments (NPCs aren't friend/foe candidates the same way other players are).

Render a generic object's display name inside <object stuff-id="..."> tags. Same identity-tagging rationale as name.

Wrap a sequence of <li> items in an ordered <list ordered="true"> envelope (markdown 1. item / 2. item lines). Flatten emits 1. , 2. , … prefixes.

Factory: a MentionResolver over the speaker's perceivable neighbors. Matches against display names (case-insensitive) and returns the first hit. Ties fall through silently (per the "silent on miss" contract). Used by VocalMixin.say, AetherMixin.tell, and the (future) emote handler when they call Mml.markdownToMml(text, resolver) on user-supplied prose.

Render a player's display name inside <player stuff-id="..."> tags. Same identity-tagging contract as name; the renderer applies friend/foe coloring on player-tagged references through the stylesheet's attribute → bucket selector.

Wrap body in <pre>...</pre> (markdown ```block```).

Wrap text in <speech>"..."</speech>, escaping the inner text.

Accepts a raw string (the common case — a literal said by the speaker) OR an already-parsed Mml fragment (the markdown-pipeline case where markdownToMml has already turned **bold**/etc. into MML). The body inside the quotes is emitted verbatim for Mml arguments and escaped for raw strings — same trust split as Mml.compose.

Wrap body in <strike>...</strike> (markdown ~~strike~~).

Sense-aware tag strip — parse the body, walk the tree, drop <sense> regions and <detail sense=> wrappings whose channel isn't in the allowed set, re-serialize.

The two strip rules differ:

• <sense channel="X">…</sense> — channel ∉ allowed → drop the tag AND its children entirely (the region is the authored sense-attributed content; it vanishes for viewers who don't perceive on X).
• <detail key="K" sense="X">…</detail> — sense ∉ allowed → drop the <detail> wrapping but KEEP the inner children flattened inline (the keyword is still readable prose; only the click-affordance disappears). <detail> with no sense= attribute defaults to 'vision'.
• All other tags — preserved with children re-serialized.

Used by senseStripAugmenter in lib/description/Visible.ts; lives here so the hard "nothing outside api/mml.ts imports api/mml/" rule is satisfied — internal parseToTree access stays scoped to this module.

Strip MML tags from a markup body, decoding the five built-in entities. Used by clients/log capture that need a plain-text projection. State-machine parser; tolerates unclosed tags by dropping their characters.

Distinct from flatten — strip removes emphasis markdown entirely (used by v1 plain-mode collapse), flatten preserves it (used by markdown round-trip / log capture).

Wrap body in <strong>...</strong> (markdown **bold**).

The escaped-text fragment: a raw string lifted into an Mml with its special characters escaped exactly once, at construction. This is the seam that lets any display value join the compose chain as a fragment — once it's an Mml, it slots into bigger fragments verbatim and is never re-escaped. The plain default for an object's getPresentationMml.

Wrap a sequence of <li> items in an unordered <list> envelope (markdown - item lines). The renderer's v1 default template emits them inline through the flatten serializer — the rich layout (proper bullets / indent) is Wave 2's layout-library concern.