`,
* `
`, `` — where CommonMark says the line is HTML content, not a
* fence) was previously dismissed here as "not an argument either way". THAT
* WAS WRONG: it is precisely the residual fail-open. The intersection guard
* below only reconciles DISAGREEMENT, so when BOTH engines open the same bogus
* fence the guard is a no-op and a live `` in a destination or title is not a closer.
masked = blankLinkDefinitions(masked, lines)
// …and the GFM FOOTNOTE definitions that pass deliberately refuses, but only
// the UNREFERENCED ones: remark-gfm drops those whole, so their bodies are
// not document text either. It reads the CURRENT mask for DEFINITIONS and a
// separate, more-blanked copy for REFERENCES (`footnoteReferenceMask`), both
// behind a `[^` guard.
//
// ITS SLOT IS CONSTRAINED ON BOTH SIDES, and neither bound is cosmetic:
// · it may not run EARLIER than the code passes, whose output is the
// definition source;
// · it may not simply be MOVED after `blankInlineLinkPayloads` /
// `blankBracketLabels` to pick up the phantom-reference fix, because
// `blankBracketLabels` blanks footnote labels "reference AND definition
// alike" — after it, EVERY reference is gone and every referenced
// definition would be over-blanked into escaped source. Hence the
// separate scratch copy instead of a reorder.
masked = blankUnreferencedFootnotes(masked, lines, folded)
// …and the INLINE link/image spelling of the same shelter, which remark
// likewise turns into href/title attributes. Container-agnostic, so like
// the definition pass it needs exactly one top-level call.
masked = blankInlineLinkPayloads(masked, folded)
// …and the BRACKET half of that same class — an image's alt, a reference
// label, a footnote label — which remark consumes into an attribute or an
// identifier. Container-agnostic, so likewise exactly one top-level call.
masked = blankBracketLabels(masked, folded)
masked = blankQuotedCode(masked, lines)
// …and the LIST-container analogue, for items whose content column exceeds
// the 3-column fence-indent cap. Monotonic, so its position among the
// block passes is not load-bearing.
masked = blankListItemCode(masked, lines)
// Comments scan the MASKED copy, not `folded` — see `blankComments`. Must
// stay LAST: it relies on every code region already being blanked.
masked = blankComments(masked, masked)
// 3. Attribute regions. Blanking the WHOLE tag would blank real ``
// closers too (and break the closed-form fixtures), so only the
// attribute run between the tag name and the `>` is cleared.
masked = blankTagAttributes(masked)
return masked
}
/** Exported for the length-preservation invariant test only. */
export const __buildCloserHaystackForTest = buildCloserHaystack
/**
* True when a well-formed `` (optional trailing whitespace) occurs at
* or after `from` in the MASKED lowercased source (see `buildCloserHaystack`).
* Substring search rather than a per-tag `RegExp` — the tag comes from
* `RAWTEXT_TAGS`, but building regexes from tag names in a hot path invites
* an injection footgun on the next edit.
*/
function hasLaterCloser(lowerSource: string, tag: string, from: number): boolean {
const needle = `` or `` closes it; `` is a different tag.
if (/^\s*>/.test(lowerSource.slice(at + needle.length, at + needle.length + 64)))
return true
cursor = at + needle.length
}
}
/**
* True when the mask considers `[from, to)` entirely code — every character
* blanked to a space (newlines are never blanked, so they count as blank).
* Both strings are the same length by construction (see `foldAsciiCase`).
*/
function isMaskedBlank(lowerSource: string, from: number, to: number): boolean {
for (let i = from; i < to; i++) {
const c = lowerSource[i]
if (c !== ' ' && c !== '\n') return false
}
return true
}
/**
* True when `span` contains a RAWTEXT opener with no matching closer INSIDE
* the span — the self-containment test the carve applies before pushing a
* protected span through verbatim. See the CARVE BALANCE GUARD in
* `escapeUnknownHtmlTags`.
*
* A closer with no opener before it is harmless (it cannot start a RAWTEXT
* span), so the counter floors at zero rather than going negative.
*
* SELF-CLOSING IS AN OPENER (round 11). HTML ignores the self-closing flag on
* non-void, non-foreign elements, so parse5 tokenizes `` as a START
* tag and enters RAWTEXT exactly like `` into a live closer — the
* fail-OPEN direction. Same line-state concept, opposite fail directions, so
* they stay two walks.
*/
interface HtmlBlockRange {
start: number
end: number
}
/** CommonMark start-condition 6 tag list (verbatim from the spec). */
const HTML_BLOCK_TYPE_6_TAGS = new Set([
'address', 'article', 'aside', 'base', 'basefont', 'blockquote', 'body',
'caption', 'center', 'col', 'colgroup', 'dd', 'details', 'dialog', 'dir',
'div', 'dl', 'dt', 'fieldset', 'figcaption', 'figure', 'footer', 'form',
'frame', 'frameset', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'head', 'header',
'hr', 'html', 'iframe', 'legend', 'li', 'link', 'main', 'menu', 'menuitem',
'nav', 'noframes', 'ol', 'optgroup', 'option', 'p', 'param', 'search',
'section', 'summary', 'table', 'tbody', 'td', 'tfoot', 'th', 'thead',
'title', 'tr', 'track', 'ul',
])
const HTML_BLOCK_START_1 = /^ {0,3}<(?:script|pre|style|textarea)(?:[ \t>]|\r?$)/i
const HTML_BLOCK_END_1 = /<\/(?:script|pre|style|textarea)>/i
const HTML_BLOCK_START_2 = /^ {0,3}') !== -1
case 3:
return line.indexOf('?>') !== -1
case 4:
return line.indexOf('>') !== -1
default:
return line.indexOf(']]>') !== -1
}
}
function htmlBlockStartKind(line: string, inParagraph: boolean): number | null {
if (line.indexOf('<') === -1) return null
if (HTML_BLOCK_START_1.test(line)) return 1
if (HTML_BLOCK_START_2.test(line)) return 2
if (HTML_BLOCK_START_3.test(line)) return 3
if (HTML_BLOCK_START_5.test(line)) return 5
if (HTML_BLOCK_START_4.test(line)) return 4
const six = HTML_BLOCK_START_6.exec(line)
if (six && HTML_BLOCK_TYPE_6_TAGS.has(six[2].toLowerCase())) return 6
// Condition 7 is the ONLY one that cannot interrupt a paragraph.
if (!inParagraph && HTML_BLOCK_START_7.test(line)) return 7
return null
}
function computeHtmlBlockRanges(text: string): HtmlBlockRange[] {
if (text.indexOf('<') === -1) return []
const ranges: HtmlBlockRange[] = []
const fences = createFenceTracker()
let kind: number | null = null
let start = 0
let lastEnd = 0
let inParagraph = false
let offset = 0
// Container state for the normalization above. `listContentCol` is the width
// of the innermost list marker seen; `openPrefixLen` is how many prefix
// COLUMNS the CURRENTLY open block consumed on its OPENING line, which decides
// whose notion of "blank line" terminates a type-6/7 block (see below).
let listContentCol = 0
let openPrefixLen = 0
for (const line of text.split('\n')) {
const lineStart = offset
const lineEnd = offset + line.length
offset = lineEnd + 1
// Columns, not characters (see `expandTabs`). Every comparison against "the
// line as written" below must use THIS, or a tab-prefixed container reads as
// a container that opened nothing.
const expanded = expandTabs(line)
const norm = stripContainerPrefix(expanded, listContentCol)
if (norm.openedListCol >= 0) listContentCol = norm.openedListCol
else if (!isBlankLine(norm.text) && norm.text === expanded) listContentCol = 0
const normBlank = isBlankLine(norm.text)
// A type-6/7 block ends at the first blank line. At top level the raw line
// decides — a bare `-` or `>` line inside a top-level HTML block is CONTENT,
// and treating it as blank would END the range early (the one
// under-detecting direction).
//
// Inside a container the container's own filler (`>`, `> >`, the item's
// indent) IS that blank line, so the block must end there — but ONLY the
// filler of the container the block actually opened in. Round 13 used the
// fully-stripped `norm.text` here, and `stripContainerPrefix` strips ANY
// container markers, not the ones that were open. So a line holding a
// DIFFERENT container's opener (` >` under a `- `, `> -` under a
// `>
`) normalized to empty, read as blank, and ended the range early —
// re-opening the very shelter the range exists to expose (verified: 1 live
// `
` written
* inside an over-long inline span and re-opened the RAWTEXT swallow this module
* exists to close. A residual note must state the fail direction PER CONSUMER;
* a single "safe direction" verdict for a value read by passes that round
* opposite ways is not a finding, it is an averaging error.
*
* RESOLVED for the haystack: the mask no longer uses a capped regex at all
* (`findInlineCodeRanges` — linear, uncapped), so an over-long inline span is
* blanked like any other and the haystack's fail-OPEN row above no longer has
* an over-cap case. Pinned by the `spanLength` axis of the swallow sweep
* (cap−k and cap+k for every shelter spelling).
* RESIDUAL, deliberately kept: the CARVE keeps its cap, and so does this pass's
* view of an over-cap span in a document the mask ALSO declines to blank — both
* of those round CLOSED per the table, i.e. they cost at worst a visible `<`.
*/
const LEFTOVER_TAG_START_RE = /<(\/?)([a-zA-Z][a-zA-Z0-9-]{0,63})(?=[\s>])/g
function escapeLeftoverTagStarts(gap: string, lowerSource: string, gapOffset: number): string {
if (gap.indexOf('<') === -1) return gap
LEFTOVER_TAG_START_RE.lastIndex = 0
return gap.replace(
LEFTOVER_TAG_START_RE,
(m: string, slash: string, tag: string, at: number) =>
isMaskedBlank(lowerSource, gapOffset + at, gapOffset + at + m.length)
? m
: `<${slash}${tag}`,
)
}
export function escapeUnknownHtmlTags(
text: string,
allowedTags: Set
= SAFE_HTML_TAGS,
): string {
if (!text || text.indexOf('<') === -1) return text
// Masked, length-preserving, lowercased whole-document copy for the RAWTEXT
// closer lookup — the closer may live in a later segment than the opener,
// so the search must span the ENTIRE source, not the segment being escaped,
// and must ignore closers that are only code samples / attribute text.
const lowerSource = buildCloserHaystack(text)
// HTML-block ranges for the CARVE BALANCE GUARD below. Computed LAZILY: only
// a protected span that actually carries an unbalanced RAWTEXT opener needs
// them, which no ordinary message has.
let htmlBlocks: HtmlBlockRange[] | null = null
const spanInsideHtmlBlock = (from: number, to: number): boolean => {
htmlBlocks ??= computeHtmlBlockRanges(text)
return htmlBlocks.some((r) => r.start < to && r.end > from)
}
// Carve out fenced code blocks AND inline-backtick spans so ``
// examples inside code are preserved verbatim.
const parts: string[] = []
let cursor = 0
PROTECTED_SPAN_RE.lastIndex = 0
let span: RegExpExecArray | null
while ((span = PROTECTED_SPAN_RE.exec(text)) !== null) {
if (span.index > cursor) {
parts.push(
escapeOutsideFences(text.slice(cursor, span.index), allowedTags, lowerSource, cursor),
)
}
// INTERSECTION GUARD (soundness, not an instance patch). A protected span
// is pushed through VERBATIM, so a live RAWTEXT opener inside one never
// reaches `escapeOutsideFences` at all and the mask's correctness is
// bypassed. Carve and mask run different engines, so the carve CAN protect
// a region the mask correctly blanked — `PROTECTED_SPAN_RE`'s closer
// alternative accepts an info string, ends its span early, desyncs, and can
// open a new span from a line CommonMark treats as ordinary text. Protect
// only what BOTH engines call code: if the mask left anything non-blank
// over this exact range, escape the span instead.
//
// CARVE BALANCE GUARD (the residual fail-open the intersection alone does
// NOT close). The intersection only reconciles DISAGREEMENT; when BOTH
// engines over-detect the SAME region it is a no-op. CommonMark says an
// HTML block (type 1 ``/``, type 6 ``) runs to its
// terminator, so a ``` line inside one is HTML CONTENT and not a fence —
// and NEITHER `createFenceTracker` nor `PROTECTED_SPAN_RE` models HTML
// blocks, so both open a bogus fence at the same line and shelter whatever
// follows. So the range check is paired with a self-containment check: a
// protected span is by definition a complete code region, therefore any
// RAWTEXT opener inside it must be BALANCED within it. An unbalanced one
// means the span is not really code — route it through the escaper. This
// is engine-independent (it needs no HTML-block tracking).
//
// GATED ON HTML-BLOCK MEMBERSHIP, NOT ON THE SPAN'S FLAVOR (round 12). The
// property that makes a protected span "not really code" is that it sits
// inside an HTML BLOCK — where CommonMark says every line is HTML content.
// Two earlier rounds gated on flavor instead and traded one hole for the
// other:
// - round 9 applied the guard to BOTH alternatives. That over-applied to
// inline code, where entity references are NOT recognized, so an escaped
// `<title>` was shown to the reader LITERALLY — and naming a tag in
// inline code (`` `
` ``) is the single most common way a docs
// answer mentions one.
// - round 11 scoped it to FENCES, justified by "an inline span cannot
// shelter a live opener: remark emits it as an `inlineCode` TEXT node, so
// parse5 never tokenizes its content". That invariant is asserted in a
// comment and holds only OUTSIDE an HTML block. Inside one, remark emits
// raw HTML, backticks are not code, and `` `<textarea>` `` on its own
// line inside `<div>` / `<pre>` / `<details>` / `<span>` sheltered a live
// opener that swallowed the rest of the message.
// Membership covers BOTH spellings with one property, and leaves ordinary
// prose inline code untouched. `isFence` is kept as an independent
// sufficient condition: a fenced span that the mask blanked but the HTML
// walk does not consider part of a block (the two engines can still desync)
// must stay under the round-9 guarantee.
// Group 1 is the fence marker, group 2 the inline backtick run.
//
// PROPERTY GUARANTEED: no protected span that is either a FENCE or inside an
// HTML BLOCK can carry an unbalanced RAWTEXT opener into the output
// verbatim. That is strictly weaker than "the carve never over-detects" — an
// over-detected span with no RAWTEXT opener in it is still pushed verbatim,
// which stays cosmetic-only.
const isFence = span[1] !== undefined
const spanEnd = span.index + span[0].length
parts.push(
isMaskedBlank(lowerSource, span.index, spanEnd) &&
!(
hasUnbalancedRawtextOpener(span[0]) &&
(isFence || spanInsideHtmlBlock(span.index, spanEnd))
)
? span[0]
: escapeOutsideFences(span[0], allowedTags, lowerSource, span.index),
)
cursor = span.index + span[0].length
}
if (cursor < text.length) {
parts.push(escapeOutsideFences(text.slice(cursor), allowedTags, lowerSource, cursor))
}
return parts.join('')
}
/**
* Walks `segment` tag by tag rather than using `String.replace`, so the regions
* the main regex did NOT consume are addressable: each gap is handed to
* `escapeLeftoverTagStarts` (see it for the over-long-attribute fail-open it
* closes), while every matched tag keeps its ORIGINAL index. Preserving that
* index matters — `hasLaterCloser` indexes `lowerSource`, which is built from
* the untouched text, so any offset drift reopens the round-5 desync class.
*/
function escapeOutsideFences(
segment: string,
allowedTags: Set<string>,
lowerSource: string,
segmentOffset: number,
): string {
const out: string[] = []
let cursor = 0
TAG_LIKE_REGEX.lastIndex = 0
let m: RegExpExecArray | null
while ((m = TAG_LIKE_REGEX.exec(segment)) !== null) {
const [match, slash, tag, rest, selfClose] = m
if (m.index > cursor)
out.push(
escapeLeftoverTagStarts(
segment.slice(cursor, m.index),
lowerSource,
segmentOffset + cursor,
),
)
const lower = tag.toLowerCase()
const escaped = `<${slash}${tag}${rest}${selfClose}>`
if (!allowedTags.has(lower)) {
out.push(escaped)
} else if (slash === '' && RAWTEXT_TAGS.has(lower)) {
// Allowlisted — but an UNCLOSED RAWTEXT opener would swallow the rest of
// the document during tokenization, before any allowlist applies.
//
// The SELF-CLOSED spelling counts as an opener (round 11): HTML ignores
// the self-closing flag on non-void, non-foreign elements, so parse5
// tokenizes `<textarea/>` as a start tag and enters RAWTEXT identically.
// Excluding it here left the entire defense — prose openers, HTML-block
// shelters, all of it — bypassable by one extra slash. `RAWTEXT_TAGS` has
// no void members, so nothing legitimate self-closes.
//
// COSMETIC COST (accepted, fail-closed): self-closing IS honored in
// foreign content, so an EMPTY `<title/>` inside `<svg>` now escapes
// rather than rendering. It carries no accessible name either way, and
// the real a11y form `<title>Chart` is unaffected. SECOND COST
// added by the same round: a protected span the balance guard deems
// not-really-code is routed through this function whole, so bare `