v0 source pure

BechString validates a bech32-style address-like string.

A bech32 string has the shape `<hrp>1<data>`: a human-readable prefix (HRP) that names the family (e.g. `g` for gno addresses, `gpub` for gno pubkeys, `cosmos` for cosmos addresses), the separator character `1`, then a data part carrying the encoded payload as lowercase alphanumerics.

If prefix != "", requires s to start with prefix+"1" exactly, and the data part to match ^[a-z0-9]{6,90}$. Use this when you know the expected family:

1sanitize.BechString(addr, "g")     // only g1...     (addresses)
2sanitize.BechString(pk,   "gpub")  // only gpub1...  (pubkeys)

If prefix == "", accepts any reasonable bech32 shape: ^[a-z]{1,16}1[a-z0-9]{6,90}$.

Syntactic only — does NOT verify the bech32 checksum. Use a true bech32 decoder if you need that. Returns the cleaned input on accept, "" on reject; on "" return, do not emit the address-link markup (the user-supplied bytes have failed shape validation and should not appear unmodified in output).

Block prepares user content for a top-level BLOCK markdown context where paragraphs, line breaks, code blocks, and other block structure should survive — but where the content must NOT be able to inject new top-level constructs (headings, lists, blockquotes, link-reference definitions, setext underlines, gnoweb extension delimiters, GFM table rows).

Output shape: every non-empty result begins AND ends with "\n\n" — CM §4.8 blank lines on both sides — so user content is guaranteed to occupy its own paragraph(s), isolated from any realm chrome that precedes OR follows it. This bounds CM §4.6 HTML block types 6 and 7 (`<div>`, `<table>`, `<form>`, arbitrary `<foo>` tags) which close on a blank line and are NOT escaped in any mode, and it defeats first-line setext promotion (`===`/`---`) that strict-mode escapes miss when the previous line is blank in the user input but non-blank in the concatenated realm output. Empty input (or input that strips entirely, e.g. a lone LRD) returns "" — no envelope is emitted.

Use for any multi-paragraph user-supplied prose that the realm concatenates into its rendered output:

• post bodies, comments, replies
• profile bios, About sections
• proposal descriptions, governance motions
• changelog entries, release notes

What Block does with each kind of attacker input:

 1User attempt                                          | Block's response
 2------------------------------------------------------|----------------------------------------------------
 3  --- preserved verbatim ---                          |
 4[text](url) inline link, ![alt](src) image            | preserved verbatim
 5------------------------------------------------------|----------------------------------------------------
 6  --- escaped / stripped / folded ---                 |
 7# heading at line-start                               | escaped → literal `# heading`
 8> quoted at line-start                                | escaped → literal `>`
 9- item, * item, + item, 1. item at line-start         | escaped
10---, ***, ___ (3+) at line-start                      | escaped
11=== or --- on its own line after non-blank text       | escaped (no setext promotion of the line above)
12<gno-card>, <gno-columns>, any <gno-…>/</gno-…> at    | escaped (wildcard match) → literal text
13  line-start                                          |
14| a | b | GFM table row (line-leading `|`)            | escaped → literal `| a | b |`
15<!--, <script>, <pre>, <style>, <textarea>, <?…?>,    | escaped (\<…) → literal text;
16  <!DOCTYPE…>, <![CDATA[…]]> at line-start            |   blocks goldmark from opening a
17  (CM §4.6 HTML block types 1-5)                      |   blank-line-NON-terminating HTML block
18[text][realm-label] ref-link USE                      | both bracket pairs escaped → \[text\]\[realm-label\]
19[^name] footnote-ref                                  | both brackets escaped → \[^name\]
20[label] bare shortcut-ref                             | both brackets escaped → \[label\]
21[label]: url link-reference definition                | whole region stripped (incl. multi-line label
22  (incl. [lab\nel]: url multi-line)                   |   `[lab\nel]: url` and any title continuation)
23[label\]: url (backslash-escaped `]`)                 | NOT stripped; brackets escaped → paragraph text
24code fence opened without close                       | autoclosed at end of input
25NUL byte (\x00)                                       | replaced with U+FFFD
26U+2028 / U+2029 / U+0085 (NEL)                        | folded to `\n`
27bidi/zero-width controls                              | stripped

COMPOSITION GOTCHA: Block's EOF fence-autoclose appends a final fence line. If you wrap Block's output with a line-prefixing builder like md.Blockquote (which prepends `> ` per line) or md.Nested, that closing fence becomes a prefixed line. The output is still safe (the fence still closes correctly) but may render awkwardly. If pixel-perfect output matters, strip a trailing blank fence line after Block.

Why backslash and not a space for `<gno-…>` lines: gnoweb's extension parsers call `util.TrimLeftSpace` on the line before tag matching, which would strip a leading space and let the tag match anyway. A leading `\` survives the trim (only ASCII whitespace + form-feed are stripped) and is consumed by the inline escape phase before Type-7 HTML block detection can fire (Type-7 requires the first non-whitespace char to be `<`).

Inline emphasis, code spans, inline links, and soft line breaks within a paragraph are PRESERVED — users can format. Pipes that are NOT at line-start stay literal so prose can still write things like `a | b`.

Idempotent: Block(Block(s)) is byte-identical to Block(s). The bracket walker strips LRDs on the first pass; remaining `[`/`]` outside inline-link/image spans are escaped to `\[`/`\]`, and already-escaped brackets are preserved on subsequent passes (pass-2 backslash-parity tracking). Still, wrap each user-supplied string exactly once — chained sanitization adds no value and burns gas.

BlockRich is the permissive counterpart of Block. Both are safe sanitizers — the distinction is what markdown structure survives:

• Block escapes line-leading block markers (`#`, `>`, `-`, `*`, `+`, `1.`), thematic breaks (`---`/`***`/`___`), and setext underlines (`===`/`---`). User content becomes paragraph-shaped.
• BlockRich PRESERVES all of those, so user content can compose headings, lists, quotes, horizontal rules, and setext-styled headings. Realm-binding defenses stay on (extension delimiters `<gno-…>`, the bracket walker for link / LRD / ref / footnote / shortcut, fence autoclose, NUL / bidi / Unicode-separator folding). GFM table-row openers are PRESERVED (see "Tables" below).

Cross-paragraph safety: BlockRich's output begins with "\n\n" AND ends with "\n\n" — CM §4.8 blank lines on both sides — so user content is guaranteed to occupy its own paragraph(s), isolated from anything the realm emits before OR after. Symmetric isolation closes four distinct attacks:

• Cross-paragraph setext promotion (backward). User content `body\n===\nmore` concatenated after realm chrome (no trailing `\n`) would, without paragraph isolation, place "chrome\nbody" in one paragraph; the `===` setext underline would then promote that merged paragraph to H1, hijacking realm chrome. The leading "\n\n" forces a paragraph break.

• Cross-paragraph GFM table promotion (backward). User content beginning with `|---|---|` (a table delimiter row) would, without a blank-line break, retroactively turn the preceding realm line into a `<thead>`. Paragraph isolation prevents the table-detection scan from crossing the boundary.

• Cross-paragraph GFM table promotion (forward). Realm chrome appended immediately after BlockRich(user) that begins with `|---|` would, without a trailing blank line, extend user's last line into a table header and pull realm chrome into the body row. The trailing "\n\n" prevents the merge.

• Lazy paragraph continuation (forward). Paragraph-shaped realm chrome appended immediately after BlockRich(user) would, via CM §5.2, merge into user's trailing paragraph and inherit any block-level decoration it carries.

First-line qualifying-setext escape (the `neuterLeadingSetextIfQualifying` pre-pass) remains in place as belt-and-suspenders: if the first non-blank line of user input matches the CM §4.3 setext-underline pattern (run of `=` or `-` with 0-3 leading spaces and only trailing whitespace), BlockRich inserts `\` before the first `=`/`-`. This is redundant given paragraph isolation but harmless and inexpensive.

Tables

BlockRich preserves line-leading `|` so user content can compose GFM tables:

1| Header A | Header B |
2|----------|----------|
3| cell a   | cell b   |

renders as a real `<table>` element. Strict Block continues to escape line-leading `|` (each row becomes literal `\| a | b |` text). When the realm authors the table itself and inserts user content into a specific cell, use TableCell — NOT BlockRich — to sanitize that cell value.

What attacker input produces what (full table, same rows as Block except where marked CHANGED):

 1User attempt                                  | BlockRich response
 2----------------------------------------------|--------------------------------------------------
 3  --- preserved (compose freely) ---          |
 4# heading at line-start                       | preserved [CHANGED from Block]
 5> quoted at line-start                        | preserved [CHANGED]
 6- item, * item, + item, 1. item               | preserved [CHANGED]
 7---, ***, ___ thematic break                  | preserved [CHANGED]
 8=== or --- setext underline                   | preserved when preceded by user text;
 9                                              | escaped (\===/\---) if the first non-blank
10                                              | line of input [CHANGED]
11| a | b | GFM table row (line-leading |)      | preserved → renders as <table> when followed by
12                                              | a delimiter row [CHANGED]
13[text](url), ![alt](src)                      | preserved verbatim [SAME]
14----------------------------------------------|--------------------------------------------------
15  --- escaped / stripped / folded ---         |
16<gno-card>, any <gno-…>/</gno-…> at line-start| escaped (wildcard match) [SAME]
17<!--, <script>, <pre>, <style>, <textarea>,   | escaped (\<…) [SAME] — Types 1-5 don't close
18  <?…?>, <!DOCTYPE…>, <![CDATA[…]]>           |   on blank lines, so `\n\n` envelope
19  at line-start (CM §4.6 HTML block types 1-5)|   doesn't isolate them; explicit escape
20[text][realm-label] ref-link USE              | both pairs escaped [SAME]
21[^name] footnote-ref                          | both brackets escaped [SAME]
22[label] bare shortcut-ref                     | both brackets escaped [SAME]
23[label]: url link-reference definition        | whole region stripped [SAME]
24[label\]: url (escaped `]`)                   | not stripped; brackets escaped [SAME]
25code fence opened without close               | autoclosed at end of input [SAME]
26NUL byte (\x00)                               | replaced with U+FFFD [SAME]
27U+2028 / U+2029 / U+0085 (NEL)                | folded to `\n` [SAME]
28bidi/zero-width controls                      | stripped [SAME]

Use BlockRich for user content the realm intends to compose with full block-level richness — typically inside a sandbox container (`<gno-card>`, `<gno-foreign>`) or a CSS-demoted region where inner headings render visually distinct from realm chrome. The realm must own the visual containment: concatenating BlockRich's output directly into a top-level page still lets the user write `# heading` at document level. BlockRich's cross-boundary setext defense prevents the worst case (reaching backwards into realm bytes), but visual containment of inner headings is the realm's CSS responsibility. gnoweb does not yet ship CSS rules that demote inner headings inside `<gno-card>` / `<gno-foreign>` — until those rules land, realms using BlockRich + a sandbox should be aware that inner headings render at their literal level.

Idempotent: BlockRich(BlockRich(s)) is byte-identical to BlockRich(s). The TrimLeft-then-"\n\n"-prepend pattern strips any leading newlines and reapplies exactly two, so the leading shape is stable across passes; the qualifying-setext escape is stable (a line beginning with `\` no longer matches the setext pattern); and the bracket walker treats already-escaped `\[`/`\]` as ordinary bytes. Empty input (or input that strips to empty, e.g. a lone link-reference definition) returns "" — realm concatenation doesn't get a stray blank line. Still, wrap each user-supplied string exactly once — chained sanitization adds no value and burns gas.

Realm-discipline boundary: BlockRich defends user input against every cross-paragraph attack listed above, but it CANNOT defend against malformed REALM chrome. Specifically, callers should emit realm chrome at flush-left column 0 around `BlockRich(user)`. If the realm chrome BEFORE the call contains an unclosed CM §4.6 Type 1 HTML tag (`<script>`, `<pre>`, `<style>`, `<textarea>`), the `\n\n` envelope does NOT close it (Type 1 closes only on the matching close tag), and user-controlled `</tag>` content can then prematurely terminate it. Indented chrome (4+ leading spaces, list-item continuations, footnote-definition body) can likewise extend across the envelope into user content. Keep chrome flush-left and Type 1 tags closed within the chrome.

PREVIEW: BlockquoteRich is currently the only in-tree caller of BlockRich; the API and the `"\n\n"` output shape may evolve once direct callers emerge.

Blockquote wraps user content as a CommonMark blockquote: each line of the cleaned content gets a "> " prefix so the renderer displays it inside a `<blockquote>` element.

Use for any multi-paragraph user-supplied text that the realm wants to render as a quotation: cited posts, attached responses, error snapshots that should visually stand out.

The content is first cleaned by Block (bidi-strip, line-ending normalize, NUL→U+FFFD, bracket walker for link/image/LRD spans, block-marker escape, code-fence auto-close at EOF, Unicode-separator fold). Block's "\n\n" cross-paragraph envelope is then stripped — the `> ` marker creates the container boundary, so the envelope would only line-prefix to empty `> ` lines top and bottom — and every remaining line is prefixed with "> ". The user content can still use inline emphasis, code spans, and nested fenced code blocks inside the quote; what it cannot do is open new top-level structure (heading, list, blockquote, GFM table row, etc.) or escape the quote.

Output shape — every non-empty result begins with "\n" and ends with "\n\n" (same shape as BlockquoteRich):

• Leading "\n" guarantees a clean blockquote opener even when the realm concatenates `chrome + Blockquote(user)` without its own newline separator.
• Trailing "\n\n" (blank line) cleanly ends the blockquote so a realm appending `Blockquote(user) + chrome` cannot pull chrome bytes into the quote via CommonMark §5.2 lazy continuation.

Empty input (or input that strips entirely, e.g. a lone LRD) returns "" — no blockquote is emitted.

Composition gotcha: Block's EOF code-fence auto-close (added when user content opens a ``` ``` ``` fence without closing it) becomes a "> ```" line at the end of the blockquote. Goldmark parses this correctly as the close of a fenced block inside the quote — the output is structurally safe — but the markdown source looks unusual to a human reviewer. If aesthetic output matters, ensure user content closes its own fences.

Not idempotent (see package doc): wraps with `> ` per line, so calling twice double-wraps and the outer call's Block step escapes the inner `>` prefixes.

Do NOT compose with BlockRich in either direction:

• Blockquote(BlockRich(s)) double-sanitizes: BlockRich preserves `#`/`>`/etc., then Blockquote's Block step escapes them again.
• BlockRich(Blockquote(s)) doesn't make sense: Blockquote already line-prefixed with `> `; BlockRich expects raw user content.

For a quoted body that can contain headings, lists, nested quotes, or thematic breaks, use BlockquoteRich.

BlockquoteRich is the permissive counterpart of Blockquote. Both wrap user content as a CommonMark blockquote (each line prefixed with `> `), but they differ in what block-level structure inside the quote survives:

• Blockquote escapes line-leading block markers, so the quoted body is paragraph-shaped — `# x` inside a Blockquote stays a literal `#`.
• BlockquoteRich PRESERVES line-leading block markers, so the quoted body can compose ATX headings, lists, thematic breaks, nested blockquotes (`> > nested`), and other block-level structure. Realm-binding defenses stay on (extension delimiters, GFM table-row openers, bracket walker, fence autoclose, NUL / bidi / Unicode-separator folding).

Output shape — every non-empty result begins with "\n" and ends with "\n\n":

• Leading "\n" guarantees a clean blockquote opener even when the realm concatenates `chrome + BlockquoteRich(user)` without its own newline separator. Without the leading "\n", chrome ending mid-line followed by "> quoted" would render `>` as literal paragraph text instead of opening a blockquote.
• Trailing "\n\n" (blank line) cleanly ends the blockquote so a realm appending `BlockquoteRich(user) + chrome` cannot pull chrome bytes into the quote via CommonMark §5.2 lazy continuation. Without the trailing blank line, paragraph chrome immediately after BlockquoteRich would render inside the quote.
• BlockRich's own leading "\n\n" (paragraph-isolation blank line) is stripped before line-prefixing — otherwise the output would carry one or two redundant empty `> ` quoted lines at the top. A single "\n" is then re-prepended at the BlockquoteRich boundary so `chrome + BlockquoteRich(user)` still lands the first `>` at column 0.
• The cross-boundary setext defense BlockRich provides is redundant inside a blockquote: a setext underline inside `> ` content can only promote a line in the same blockquote, never reach realm bytes (different CM container). BlockRich still applies it, harmlessly.

What attacker input produces what (rows that differ from Blockquote are marked CHANGED):

 1User attempt                                  | BlockquoteRich response
 2----------------------------------------------|------------------------------------------------
 3  --- preserved inside `> ` quote ---         |
 4# heading                                     | preserved as `> # heading` [CHANGED]
 5> nested quote                                | preserved as `> > nested quote` [CHANGED]
 6- item, * item, + item, 1. item               | preserved as `> - item` etc. [CHANGED]
 7---, ***, ___ thematic break                  | preserved [CHANGED]
 8=== or --- setext underline                   | preserved when preceded by user text;
 9                                              | escaped (\===/\---) if first non-blank
10                                              | line of input [CHANGED]
11| a | b | GFM table row (line-leading |)      | preserved → renders as <table> inside the
12                                              | blockquote when followed by a delimiter row [CHANGED]
13[text](url), ![alt](src)                      | preserved verbatim [SAME]
14----------------------------------------------|------------------------------------------------
15  --- escaped / stripped / folded ---         |
16<gno-card>, any <gno-…>/</gno-…> at line-start| escaped (wildcard match) [SAME]
17<!--, <script>, <pre>, <style>, <textarea>,   | escaped (\<…) [SAME] — CM §4.6 Types 1-5
18  <?…?>, <!DOCTYPE…>, <![CDATA[…]]>           |   don't close on blank lines; without escape
19  at line-start                               |   they would swallow chrome past the `> ` quote
20[text][realm-label] ref-link USE              | both pairs escaped [SAME]
21[^name] footnote-ref                          | both brackets escaped [SAME]
22[label] bare shortcut-ref                     | both brackets escaped [SAME]
23[label]: url link-reference definition        | whole region stripped [SAME]
24code fence opened without close               | autoclosed at end of input [SAME]
25NUL byte (\x00)                               | replaced with U+FFFD [SAME]
26U+2028 / U+2029 / U+0085 (NEL)                | folded to `\n` [SAME]
27bidi/zero-width controls                      | stripped [SAME]

Use BlockquoteRich when the realm wants to render user content as a quotation that itself reads like authored markdown — the visual CSS containment of `<blockquote>` already demotes inner headings relative to realm chrome, so the "inner headings need a sandbox" caveat that applies to BlockRich at top level does not apply here.

Not idempotent: like Blockquote, calling twice double-wraps — `BlockquoteRich(BlockquoteRich(s))` produces `> > content`, nesting the quote a level deeper each pass.

Empty input (or input that reduces to nothing after BlockRich, e.g. a lone link-reference definition) returns "" — no blockquote is emitted and neither the leading "\n" nor the trailing "\n\n" shape applies.

CodeBlock wraps user content as a CommonMark fenced code block. Use for any user-derived multi-line snippet that should render as a code block: log excerpts, JSON dumps, error backtraces, config snippets, posted code samples.

Behavior:

• Bidi/zero-width controls are stripped.
• CR/CRLF line endings are normalized to LF; Unicode separators (NEL U+0085, U+2028, U+2029) are folded to LF for line-count consistency.
• NUL is replaced with U+FFFD per CM §2.3.
• The wrapping fence is at least 3 backticks (CM §4.5 minimum) and sized to outscan internal backticks — an attacker cannot embed a closing fence in the content.

Empty content emits an empty fenced block ("```\n\n```\n"), which is valid CommonMark and renders as an empty `<pre><code></code></pre>`.

Not idempotent (see package doc).

CodeFence returns a string of backticks long enough to wrap content as a CommonMark fenced code block without the content's own backticks closing the fence prematurely.

Returned length N = max(minCount, longestBacktickRunInContent + 1). Use N backticks both before and after the content:

1fence := sanitize.CodeFence(userCode, 3)
2out += fence + "\n" + userCode + "\n" + fence + "\n"

Typical minCount values:

• 1 for inline code spans (`x`)
• 3 for block fenced code (CommonMark §4.5 requires ≥3)

`minCount < 1` is clamped to 1. Empty content returns strings.Repeat("`", max(minCount, 1)). Never panics.

Most realms should reach for InlineCode / CodeBlock / LanguageCodeBlock below, which call CodeFence internally and emit the full code block for you. Call CodeFence directly only when you're rolling a custom fence emitter (e.g. a renderer that needs the fence length but emits the body differently).

FootnoteDefinition emits a GFM footnote definition — the `[^name]: body` form that introduces a footnote whose body is rendered in the page footer (or wherever the renderer chooses to place it). Other parts of the markdown reference the footnote by writing `[^name]` inline.

Use for any realm-rendered footnote where the body text comes from user input. The realm picks the footnote name (passed as `name`, validated by FootnoteLabel — failure here returns ""); the user's content goes in `text`, which is sanitized via Block.

Contract:

• `name`: passed raw, validated as a FootnoteLabel (^[A-Za-z0-9_-]{1,64}$). Reject → return "".
• `text`: passed raw multi-paragraph user prose, cleaned via Block (bidi-strip, line-ending normalize, LRD strip, block-marker escape, ref-link USE escape, fence auto-close).

Empty body → returns "" (a label without body is not a valid footnote definition; the markdown would parse as a paragraph containing the label).

Output shape:

1[^name]:
2    line 1 of body
3    line 2 of body
4    ...

The label sits on its own line and each body line gets a 4-space indent — the GFM continuation rule that keeps multi-paragraph body text bound to the footnote rather than detaching as a new paragraph.

Not idempotent (see package doc): composes Block internally; passing already-sanitized body text double-escapes.

FootnoteLabel validates an identifier used as a footnote name, link- reference-definition label, or {#id} anchor: ^[A-Za-z0-9_-]{1,64}$. Strips bidi/zero-width first. Returns s if valid, "" otherwise.

Use for every shape where a markdown identifier is treated as an opaque key by the parser:

• footnote-definition labels: [^FootnoteLabel(name)]: body
• footnote-reference labels: see [^FootnoteLabel(name)]
• link-reference-definition labels: [FootnoteLabel(label)]: url
• reference-link USE labels: [text][FootnoteLabel(label)]
• goldmark auto-anchor {#id}: # Heading {#FootnoteLabel(id)}

The shared validator name reflects the shared charset and shared security goal — keep untrusted bytes out of any parser-managed identifier slot.

On "" return, omit the footnote / LRD / anchor entirely rather than emitting it with raw user bytes.

HTMLEscape prepares user content for an HTML lexical slot inside markdown — covers attribute values, element bodies, and HTML comment bodies:

1<gno-card type="..." caption="X">         attribute value
2<gno-alert title="X">                     attribute value
3<h5>X</h5>                                element body
4<details><summary>X</summary>...          element body
5<!-- X -->                                comment body (safe: `>`
6                                          becomes `&gt;`, so user
7                                          cannot inject `-->`)

HTMLEscape escapes the union of attribute-breaking and body-breaking characters (`<`, `>`, `&`, `"`, `'`), so one function safely serves every HTML lexical context. Callers don't have to remember which subset to use for which slot.

Pick the right helper — markdown title and HTML attribute share the look but use different escape rules:

1[text](url "X")              → LinkTitle      (markdown title)
2<span title="X">             → HTMLEscape     (HTML attribute)
3<h5>X</h5>                   → HTMLEscape     (HTML element body)

Swapping InlineText for HTMLEscape is wrong: markdown's backslash escapes survive into the rendered HTML as literal `\*`. Swapping LinkTitle for HTMLEscape is also wrong: `&` written inside a markdown title renders as the literal characters `&`.

Not idempotent (see package doc): calling twice produces `&` → `&amp;`.

ImageURL validates a URL for use as an image src. Kept separate from URL — not a parameterized variant — because the allowlist shapes differ qualitatively (data:image/* vs. mailto:) and a single boolean flag would invite callers to pass the wrong default.

Allowlist:

• http, https
• schemeless relative URLs starting with /, ./, or .. (rejects // protocol-relative — tracking-pixel vector)
• data:image/svg+xml, data:image/png, data:image/jpeg, data:image/gif, data:image/webp

Any other data: subtype is rejected — data:text/html etc. would render as inline HTML and execute embedded scripts.

DEPLOYMENT PRECONDITION: data: URIs encode the bytes of the image directly into the markup, so a malicious sender can construct an image whose pixel dimensions are arbitrarily large at minimal byte cost. The deploying gnoweb instance MUST clamp rendered image dimensions via CSS (e.g. `max-width: 100%; max-height: <bound>`). Without that cap, a single image can blow out the page layout or exhaust the browser's memory.

Returns "" if the URL is empty after trim or fails the allowlist.

InlineCode wraps user content as a CommonMark inline code span — the `code` in “ `code` “. Use for any user-derived token, identifier, or short literal that should render in monospace inside running prose: variable names, hashes, hex addresses, token symbols, error codes, package paths, transaction IDs.

Inline code spans cannot span lines (a `\n` inside the content would end the span and leave the surrounding backticks as literal text), so all line breaks — CR / CRLF / LF, NEL (U+0085), U+2028, U+2029 — are folded to a single space. If you want each line of user content on its own row, use CodeBlock instead.

Behavior:

• Bidi/zero-width controls are stripped (browsers honor bidi marks inside `<code>`, so leaving them would let stored bytes display as something different).
• NUL is replaced with U+FFFD.
• The wrapping fence is one backtick longer than the longest backtick run in the content, so internal backticks can never close the span prematurely.
• A single space pad is added on each side when content starts or ends with “ ` “ or space, so leading/trailing backticks render literally rather than fusing with the fence (the renderer strips one space from each side per CommonMark spec).

Empty input returns "" rather than a literal two-backtick string (which CommonMark parses as text, not as an empty code span). If you use InlineCode as link text and it returns "", omit the link entirely.

Not idempotent (see package doc): wraps with a fence, so calling twice double-wraps.

InlineText prepares an arbitrary user string for an INLINE markdown slot — anywhere the rendered output stays on a single line and lives inside a larger markdown construct.

Use for:

• link text: [InlineText(label)](url)
• heading text: # InlineText(title)
• bold/italic body: **InlineText(name)**
• image alt text: 
• single-line block-context slots: > [!NOTE] InlineText(title) > Author: InlineText(name)

Multi-paragraph prose belongs in Block, not InlineText. InlineText folds every newline to a single space (so paragraph structure is erased) and escapes inline-active CommonMark punctuation:

1\ * _ [ ] ( ) ~ > - + . ! ` # < &

Two characters are intentionally NOT escaped:

• `|` — only meaningful in GFM table rows. Leaving it literal here lets TableCell (which calls InlineText then escapes `|` itself) avoid double-escaping pipes into `\\|`.
• `=` — only meaningful as a setext heading underline, which is a line-level construct. Escaping `=` inline would mangle expressions like `x = 1` for no benefit.

Not idempotent (see package doc).

LanguageCodeBlock wraps user content as a fenced code block tagged with a programming-language hint (the "info string" after the opening fence, e.g. `go` in ```` ```go ````) so the renderer can apply syntax highlighting.

An invalid `language` tag silently falls back to a tagless fence — the helper never returns an error or panics. If a realm author is debugging "why is my Go highlighting gone?", the input failed the language validator (charset ^[a-zA-Z0-9_+-]{1,32}$ after bidi-strip). This fallback exists because an unvalidated tag could contain a newline that injects content (e.g. a heading) onto what becomes the opening fence line.

Content is cleaned exactly as in CodeBlock (bidi-strip, CR/CRLF normalize to LF, NEL/U+2028/U+2029 fold to LF, NUL→U+FFFD, fence sized to outscan internal backticks).

Not idempotent (see package doc).

LanguageName validates the language tag (a.k.a. "info string") for a fenced code block — the `go` in:

1```go
2fmt.Println("hi")
3```

Charset: ^[a-zA-Z0-9_+-]{1,32}$ — letters, digits, `_`, `+`, `-`, up to 32 bytes. Strips bidi/zero-width first.

Returns the cleaned input if valid, "" otherwise. A "" return means the caller should emit a language-less fence (``` without a tag) rather than letting the user pick the syntax highlighter — which could otherwise be used to inject newlines or block markers into what becomes the opening fence line.

LinkReferenceDefinition emits a CommonMark link reference definition (CM §4.7) — the `[label]: url "title"` form that other parts of the markdown reference by writing `[text][label]` or `[label]` (shortcut).

Use for any realm-rendered LRD where the realm owns the label but any of the URL or title come from user input. The user content for the URL goes through URL (allowlist-based — reject → ""); the title goes through LinkTitle (escape).

Contract:

• `label`: passed raw, validated as a FootnoteLabel (^[A-Za-z0-9_-]{1,64}$). Realms should choose a namespaced label using dashes (e.g. `r-myrealm-help`) so shortcut-reference invocations from user content can't collide with bare prose (`[help]`, `[click here]`). `/` is not in the FootnoteLabel charset; reject → return "".
• `url`: passed raw, sanitized via URL. If URL rejects, the LRD is skipped (return "").
• `title`: passed raw, sanitized via LinkTitle. Empty title → no title clause emitted.

The output is framed with leading and trailing blank lines so that the definition cannot accidentally fuse with adjacent paragraph content into a setext underline or a continuation line.

Not idempotent (see package doc).

LinkTitle prepares user content for a CommonMark link-title or image-title slot — the optional quoted text after the URL in any of these forms:

1[text](url "TITLE")
2![alt](src "TITLE")
3[label]: url "TITLE"

Escapes the inline-active set plus `"` and `'` (the title delimiters that aren't already in the inline set; `(` and `)` are), so the caller can choose any of the three title-quote styles safely.

Pick the right helper for the slot — markdown title and HTML attribute share the look but use different escape rules:

1[text](url "X")              → LinkTitle      (markdown title)
2<a title="X">                → HTMLEscape     (HTML attribute)
3<h5>X</h5>                   → HTMLEscape     (HTML element body)

Swapping HTMLEscape for LinkTitle is wrong: HTML's `&` written inside a markdown title renders as the literal characters `&`. Swapping LinkTitle for HTMLEscape is wrong: markdown's `\"` survives into the rendered HTML as a literal backslash-quote.

Not idempotent (see package doc).

NestedPrefix validates a prefix string for line-prefixing builders like md.Nested, which prepends `prefix` to every line of content to render the content as a nested/indented sub-block.

Allowed: any string matching `^[ \t>]*$` — spaces, tabs, blockquote `>` chars only. Anything else (a `#`, a `-`, a letter) would let a caller turn benign sub-content into a heading, list, or paragraph at the wrong nesting level.

Returns s if valid, "" otherwise. Strips bidi/zero-width first — otherwise an invisible character hidden inside a `>` prefix would be replicated on every nested content line, producing per-line display-vs-storage divergence.

On "" return, fall back to a known-safe prefix literal (e.g. `"> "`) or skip the nesting entirely. Do not emit the raw user-supplied prefix.

NormalizeBreaks unifies CR-LF and lone CR to LF (CommonMark §2.2 line endings only — does NOT touch U+2028/U+2029). Use it when comparing or hashing user input that may have been authored on different platforms (Windows CRLF vs. Unix LF), so equivalent strings normalize to the same bytes. Idempotent.

Thin wrapper over chain/markdown.NormalizeBreaks.

StripBidiAndZeroWidth removes Unicode bidi controls and zero-width characters (U+200B-D, U+200E-F, U+202A-E, U+2066-9, U+FEFF) from s. Use it when storing or comparing user-supplied strings outside of a markdown context — for example, before saving a display name to state, or before hashing a search query. Idempotent: calling twice gives the same result.

Thin wrapper over chain/markdown.StripBidiAndZeroWidth.

TableCell prepares user content for a GFM table cell — the bytes between two `|` column delimiters in a table row like `| cell-a | cell-b | cell-c |`. An unescaped `|` inside cell content would open a new column, letting a malicious user shift every column to its right.

On top of InlineText's behavior, TableCell:

• escapes `|` to `\|` so user content can't end the cell early.
• replaces tabs with single spaces. CommonMark expands tabs to the next multiple-of-4 column boundary (variable 1-4 spaces), which would shift the displayed cell-content width unpredictably and confuse table alignment.

Not idempotent (see package doc).

URL validates a URL for use as a link href, percent-encodes unsafe bytes, and rejects anything outside the allowlist of schemes.

Allowlist:

• http, https
• mailto (rejected if it carries any query: prefill phishing via body, subject, cc, etc. Both '?' and '&' are rejected; see linkSchemeAllowed for why '&' counts.)
• any URL WITHOUT a scheme — relative paths (`/path`, `./rel`, `bare-path`), query-only (`?q=v`), fragment-only (`#anchor`). A `:` appearing inside the URL (e.g. `/path:foo`, `?q=a:b`) is NOT a scheme separator per RFC 3986 — only `:` immediately after a leading `[a-zA-Z][a-zA-Z0-9+.-]*` counts.

Rejected (have an unknown scheme):

• javascript:, data:, vbscript:, blob:, file:, etc.
• `//host/...` (protocol-relative — tracking-pixel vector)

Returns "" if the URL is empty after trim or fails the allowlist.

UserName validates the r/sys/users-registration charset: ^[a-z][a-z0-9]*([_-][a-z0-9]+)*$ length ≤ 64.

The native MatchCharsetN enforces the leading-letter + tail-charset shape and length bound; this helper also performs the bidi-strip pre-pass. The "no consecutive [_-]" rule from r/sys/users is NOT enforced here (it's a registration-policy rule, not a sanitization concern — registrations go through r/sys/users itself).

Returns the (bidi-stripped) input if valid, "" otherwise. On a "" return, do not emit the user-mention markup at all (e.g. skip the `[@user](/u/user)` link); falling back to the raw user-supplied string would defeat the validation.