From 2c865f469ab7938612a994ff602ec490d5dc2d29 Mon Sep 17 00:00:00 2001
From: Vincent Peng <mail@vincentpeng.me>
Date: Thu, 8 Oct 2026 23:07:37 +1100
Subject: [PATCH 1/8] Render supported inline HTML tags instead of dropping
 them

Inline raw-HTML nodes (InlineHTML) were previously dropped during inline
conversion because they don't conform to InlineConvertible. This adds an
AST-level InlineHTMLRewriter that maps a supported formatting subset onto
equivalent Markdown nodes or InlineAttributes carriers before conversion:

- <br> -> line break, <wbr> -> zero-width space
- <b>/<strong> -> strong, <i>/<em> -> emphasis
- <s>/<del>/<strike> -> strikethrough
- <u>/<ins>, <mark>, <sub>/<sup> -> InlineAttributes, now rendered by a
  new InlineConvertible conformance (underline, highlight, baseline offset)
- <code>/<kbd>/<samp>/<tt> -> inline code
- <a href> -> link

HTML comments are dropped. Unmatched, unsupported, or malformed tags keep
their source as literal text so documents degrade gracefully. An open tag
with no matching close applies to the rest of the inline container, which
keeps mid-stream documents sensible while a tag is still arriving.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 README.md                                     |   3 +-
 .../Inline/Markdown+InlineConvertible.swift   |  45 ++++
 .../Parser/MarkdownParserImpl.swift           |   9 +
 .../Parser/Rewriters/InlineHTMLRewriter.swift | 232 ++++++++++++++++++
 .../Scanners/MarkupPostParsingRewriter.swift  |  12 +
 Sources/MarkdownText/Utilities/MDFont.swift   |  11 +
 .../InlineHTMLRewriterTests.swift             | 146 +++++++++++
 7 files changed, 457 insertions(+), 1 deletion(-)
 create mode 100644 Sources/MarkdownText/Parser/Rewriters/InlineHTMLRewriter.swift
 create mode 100644 Tests/MarkdownTextTests/InlineHTMLRewriterTests.swift

diff --git a/README.md b/README.md
index efae63a8..ab3cb1f2 100644
--- a/README.md
+++ b/README.md
@@ -113,12 +113,13 @@ The renderer targets the subset of CommonMark + GitHub-flavored Markdown that LL
 - [x] Inline LaTeX math via `\( … \)`
 - [x] Display LaTeX math via `$$ … $$`
 - [x] Inline citation pills
+- [x] Inline HTML formatting tags — `<br>`, `<b>`/`<strong>`, `<i>`/`<em>`, `<s>`/`<del>`, `<u>`/`<ins>`, `<mark>`, `<sub>`/`<sup>`, `<code>`/`<kbd>`/`<samp>`/`<tt>`, `<a href>`, `<wbr>` (unmatched or unsupported tags render as literal text)
 
 ### Not yet supported
 
 - [ ] Footnotes (`[^1]`)
 - [ ] Highlight (`==text==`), superscript (`^x^`), subscript (`~x~`)
-- [ ] Raw HTML (`<details>`, `<kbd>`, `<aside>`, …) — kept inline as text
+- [ ] Block-level raw HTML (`<details>`, `<aside>`, …) — kept inline as text
 - [ ] GitHub alerts (`> [!NOTE]`) — rendered as plain block quotes
 - [ ] Container directives (`::: warning … :::`) and admonitions (`!!! note`)
 - [ ] Mermaid / PlantUML diagrams — rendered as fenced code
diff --git a/Sources/MarkdownText/Inline/Markdown+InlineConvertible.swift b/Sources/MarkdownText/Inline/Markdown+InlineConvertible.swift
index 952cdf90..ac6e36cc 100644
--- a/Sources/MarkdownText/Inline/Markdown+InlineConvertible.swift
+++ b/Sources/MarkdownText/Inline/Markdown+InlineConvertible.swift
@@ -187,6 +187,51 @@ extension Markdown.InlineCode: InlineConvertible {
   }
 }
 
+extension Markdown.InlineAttributes: InlineConvertible {
+
+  /// Attribute keys this renderer understands inside `attributes`. Produced by
+  /// `InlineHTMLRewriter` for tags that have no dedicated Markdown node
+  /// (`<u>`/`<ins>`, `<mark>`, `<sub>`, `<sup>`).
+  private static let enabledKeyRegex = try? Regex(#"([a-zA-Z]+)\s*:\s*true"#)
+
+  private var enabledKeys: Set<String> {
+    guard let regex = Self.enabledKeyRegex else { return [] }
+    var keys = Set<String>()
+    for match in attributes.matches(of: regex) {
+      if let key = match.output[1].substring {
+        keys.insert(String(key))
+      }
+    }
+    return keys
+  }
+
+  func convert(attributeContainer: NSAttributeContainer, config: MarkdownRenderConfig) -> NSMutableAttributedString {
+    var container = attributeContainer
+    let font = attributeContainer[.font] as? MDFont ?? config.paragraphStyle.textFonts.normal
+    let keys = enabledKeys
+    if keys.contains("subscript") {
+      container[.font] = font.scaled(by: 0.75)
+      container[.baselineOffset] = -font.pointSize * 0.2
+    }
+    if keys.contains("superscript") {
+      container[.font] = font.scaled(by: 0.75)
+      container[.baselineOffset] = font.pointSize * 0.35
+    }
+    if keys.contains("underline") {
+      container[.underlineStyle] = NSUnderlineStyle.single.rawValue
+      container[.underlineColor] = container[.foregroundColor]
+    }
+    if keys.contains("highlight") {
+      container[.backgroundColor] = MDColor.systemYellow.withAlphaComponent(0.45)
+    }
+    let str = NSMutableAttributedString()
+    self.inlineConvertibleChildren.forEach { convertible in
+      str.append(convertible.convert(attributeContainer: container, config: config))
+    }
+    return str
+  }
+}
+
 extension Markdown.Table.Cell: InlineConvertible {
 
   func convert(attributeContainer: NSAttributeContainer, config: MarkdownRenderConfig) -> NSMutableAttributedString {
diff --git a/Sources/MarkdownText/Parser/MarkdownParserImpl.swift b/Sources/MarkdownText/Parser/MarkdownParserImpl.swift
index 433c0ac1..8b22cc60 100644
--- a/Sources/MarkdownText/Parser/MarkdownParserImpl.swift
+++ b/Sources/MarkdownText/Parser/MarkdownParserImpl.swift
@@ -13,6 +13,8 @@ public final class MarkdownParserImpl: MarkdownParser {
     PartialTableMarkupPostParsingRewriter()
   ]
 
+  private let inlineHTMLRewriter = InlineHTMLMarkupPostParsingRewriter()
+
   private let imageBlockRewriter = ImageBlockMarkupPostParsingRewriter()
 
   private let latexPreprocessor: LaTexPreProcessor
@@ -39,6 +41,13 @@ public final class MarkdownParserImpl: MarkdownParser {
       }
     }
 
+    if let rewrittenDoc = inlineHTMLRewriter.rewriteIfApplicable(document: result.document) {
+      result = MarkdownParseResult(
+        document: rewrittenDoc,
+        speculativeRewritten: result.speculativeRewritten
+      )
+    }
+
     if option.imageSupport {
       if let rewrittenDoc = imageBlockRewriter.rewriteIfApplicable(document: result.document) {
         result = MarkdownParseResult(
diff --git a/Sources/MarkdownText/Parser/Rewriters/InlineHTMLRewriter.swift b/Sources/MarkdownText/Parser/Rewriters/InlineHTMLRewriter.swift
new file mode 100644
index 00000000..b1a75fff
--- /dev/null
+++ b/Sources/MarkdownText/Parser/Rewriters/InlineHTMLRewriter.swift
@@ -0,0 +1,232 @@
+//
+//  Copyright (c) Microsoft Corporation. All rights reserved.
+//  Licensed under the MIT License. See LICENSE in the project root for license information.
+//
+
+import Markdown
+
+/// Rewrites supported inline raw-HTML tags into their Markdown equivalents so
+/// they render instead of being dropped by inline conversion.
+///
+/// Supported mappings:
+/// - `<br>` / `<br/>` → line break, `<wbr>` → zero-width space
+/// - `<b>` / `<strong>` → strong, `<i>` / `<em>` → emphasis
+/// - `<s>` / `<del>` / `<strike>` → strikethrough
+/// - `<u>` / `<ins>` → underline, `<mark>` → highlight
+/// - `<sub>` / `<sup>` → sub/superscript
+/// - `<code>` / `<kbd>` / `<samp>` / `<tt>` → inline code
+/// - `<a href="…">` → link
+///
+/// Comments are dropped. Unsupported or unmatched tags render as literal text
+/// so their source stays visible. An open tag with no matching close applies
+/// to the rest of the inline container (browser-style auto-close), which keeps
+/// streamed documents sensible while a tag is still arriving.
+final class InlineHTMLRewriter: MarkupRewriter {
+
+  private enum Tag {
+    case open(name: String, attributes: String)
+    case close(name: String)
+    case comment
+    case other
+  }
+
+  private static let pairedTags: Set<String> = [
+    "b", "strong", "i", "em", "s", "del", "strike",
+    "u", "ins", "mark", "sub", "sup",
+    "code", "kbd", "samp", "tt", "a"
+  ]
+
+  private static let hrefRegex = try? Regex(#"href\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))"#)
+
+  func visitParagraph(_ paragraph: Paragraph) -> Markup? { rewriteInlineChildren(paragraph) }
+  func visitHeading(_ heading: Heading) -> Markup? { rewriteInlineChildren(heading) }
+  func visitTableCell(_ tableCell: Table.Cell) -> Markup? { rewriteInlineChildren(tableCell) }
+  func visitEmphasis(_ emphasis: Emphasis) -> Markup? { rewriteInlineChildren(emphasis) }
+  func visitStrong(_ strong: Strong) -> Markup? { rewriteInlineChildren(strong) }
+  func visitStrikethrough(_ strikethrough: Strikethrough) -> Markup? { rewriteInlineChildren(strikethrough) }
+  func visitLink(_ link: Link) -> Markup? { rewriteInlineChildren(link) }
+  func visitInlineAttributes(_ attributes: InlineAttributes) -> Markup? { rewriteInlineChildren(attributes) }
+  func visitImage(_ image: Image) -> Markup? { rewriteInlineChildren(image) }
+
+  /// Recursively visits the container's children first, then rewrites the tag
+  /// sequences at this level. Containers without `InlineHTML` are returned
+  /// unchanged so untouched subtrees keep their identity.
+  private func rewriteInlineChildren<Container: InlineContainer & Markup>(_ container: Container) -> Markup? {
+    guard Self.containsInlineHTML(container) else { return container }
+    // `defaultVisit` is `mutating` on the non-class-bound visitor protocol, so
+    // it must be called through a variable; `self` is a class reference here.
+    var mutableSelf = self
+    guard var visited = mutableSelf.defaultVisit(container) as? Container else { return container }
+    visited.setInlineChildren(process(Array(visited.children)))
+    return visited
+  }
+
+  /// Whether the subtree contains any `InlineHTML` node. Used to prune
+  /// containers (and whole documents) that need no rewriting.
+  static func containsInlineHTML(_ markup: Markup) -> Bool {
+    markup.children.contains { $0 is InlineHTML || containsInlineHTML($0) }
+  }
+
+  private func process(_ input: [Markup]) -> [InlineMarkup] {
+    var output: [InlineMarkup] = []
+    var index = 0
+    while index < input.count {
+      guard let html = input[index] as? InlineHTML else {
+        if let markup = input[index] as? InlineMarkup {
+          output.append(markup)
+        }
+        index += 1
+        continue
+      }
+      switch classify(html) {
+      case .comment:
+        index += 1
+      case .other, .close:
+        output.append(Text(html.rawHTML))
+        index += 1
+      case .open(let name, let attributes):
+        if name == "br" {
+          output.append(LineBreak())
+          index += 1
+          continue
+        }
+        if name == "wbr" {
+          output.append(Text("\u{200B}"))
+          index += 1
+          continue
+        }
+        guard Self.pairedTags.contains(name) else {
+          output.append(Text(html.rawHTML))
+          index += 1
+          continue
+        }
+        if let closeIndex = findClosingIndex(named: name, in: input, from: index + 1) {
+          let inner = process(Array(input[(index + 1)..<closeIndex]))
+          if let wrapped = wrapPair(name: name, attributes: attributes, inner: inner) {
+            output.append(wrapped)
+          } else {
+            output.append(Text(html.rawHTML))
+            output.append(contentsOf: inner)
+            output.append(Text((input[closeIndex] as? InlineHTML)?.rawHTML ?? ""))
+          }
+          index = closeIndex + 1
+        } else {
+          let inner = process(Array(input[(index + 1)...]))
+          if let wrapped = wrapPair(name: name, attributes: attributes, inner: inner) {
+            output.append(wrapped)
+          } else {
+            output.append(Text(html.rawHTML))
+            output.append(contentsOf: inner)
+          }
+          index = input.count
+        }
+      }
+    }
+    return output
+  }
+
+  private func classify(_ html: InlineHTML) -> Tag {
+    let raw = html.rawHTML.trimmingCharacters(in: .whitespaces)
+    if raw.hasPrefix("<!--") { return .comment }
+    guard raw.count > 2, raw.hasPrefix("<"), raw.hasSuffix(">") else { return .other }
+    var inner = String(raw.dropFirst().dropLast())
+    if inner.hasPrefix("/") {
+      inner.removeFirst()
+      let name = inner.split(whereSeparator: { $0 == " " || $0 == "\t" || $0 == "/" }).first.map(String.init) ?? ""
+      return name.first?.isLetter == true ? .close(name: name.lowercased()) : .other
+    }
+    // A trailing "/" does not close non-void elements in HTML5, so `<b/>x`
+    // behaves like `<b>x`; the tag is still treated as an open.
+    if inner.hasSuffix("/") { inner = String(inner.dropLast()) }
+    guard let nameEnd = inner.firstIndex(where: { $0 == " " || $0 == "\t" || $0 == "\n" }) else {
+      let name = inner.lowercased()
+      return name.first?.isLetter == true ? .open(name: name, attributes: "") : .other
+    }
+    let name = String(inner[..<nameEnd]).lowercased()
+    guard name.first?.isLetter == true else { return .other }
+    return .open(name: name, attributes: String(inner[nameEnd...]))
+  }
+
+  /// Finds the matching `</name>` for an open tag at `start - 1`, counting
+  /// nested same-name tags. Other tags do not affect depth, matching how
+  /// browsers auto-close interleaved markup (the stray closer then renders
+  /// literally at the outer level).
+  private func findClosingIndex(named name: String, in input: [Markup], from start: Int) -> Int? {
+    var depth = 0
+    for index in start..<input.count {
+      guard let html = input[index] as? InlineHTML else { continue }
+      switch classify(html) {
+      case .open(let tagName, _) where tagName == name:
+        depth += 1
+      case .close(let tagName) where tagName == name:
+        if depth == 0 { return index }
+        depth -= 1
+      default:
+        continue
+      }
+    }
+    return nil
+  }
+
+  /// Wraps the processed children of a matched tag pair, or returns `nil` when
+  /// the pair cannot be represented (the caller then renders it literally).
+  private func wrapPair(name: String, attributes: String, inner: [InlineMarkup]) -> InlineMarkup? {
+    switch name {
+    case "b", "strong":
+      return Strong(inner)
+    case "i", "em":
+      return Emphasis(inner)
+    case "s", "del", "strike":
+      return Strikethrough(inner)
+    case "u", "ins":
+      return attributeWrap("underline", inner)
+    case "mark":
+      return attributeWrap("highlight", inner)
+    case "sub":
+      return attributeWrap("subscript", inner)
+    case "sup":
+      return attributeWrap("superscript", inner)
+    case "code", "kbd", "samp", "tt":
+      return InlineCode(inner.map { $0.plainText }.joined())
+    case "a":
+      guard let href = hrefValue(in: attributes),
+            let children = recurring(inner) else { return nil }
+      return Link(destination: href, children)
+    default:
+      return nil
+    }
+  }
+
+  /// `InlineAttributes` children must be `RecurringInlineMarkup`, so stacked
+  /// attribute tags (`<u><sup>x</sup></u>`) compose by merging keys into a
+  /// single node. A non-recurring child makes the pair render literally.
+  private func attributeWrap(_ key: String, _ inner: [InlineMarkup]) -> InlineMarkup? {
+    if inner.count == 1, let nested = inner.first as? InlineAttributes {
+      let children = Array(nested.children).compactMap { $0 as? (any RecurringInlineMarkup) }
+      guard children.count == nested.childCount else { return nil }
+      return InlineAttributes(attributes: mergedAttributes(nested.attributes, key: key), children)
+    }
+    guard let children = recurring(inner) else { return nil }
+    return InlineAttributes(attributes: "{\(key):true}", children)
+  }
+
+  private func mergedAttributes(_ attributes: String, key: String) -> String {
+    guard attributes.hasSuffix("}") else { return attributes }
+    return String(attributes.dropLast()) + ",\(key):true}"
+  }
+
+  private func recurring(_ inner: [InlineMarkup]) -> [any RecurringInlineMarkup]? {
+    let children = inner.compactMap { $0 as? (any RecurringInlineMarkup) }
+    return children.count == inner.count ? children : nil
+  }
+
+  private func hrefValue(in attributes: String) -> String? {
+    guard let regex = Self.hrefRegex, let match = attributes.firstMatch(of: regex) else { return nil }
+    for index in 1...3 {
+      if let substring = match.output[index].substring {
+        return String(substring)
+      }
+    }
+    return nil
+  }
+}
diff --git a/Sources/MarkdownText/Parser/Scanners/MarkupPostParsingRewriter.swift b/Sources/MarkdownText/Parser/Scanners/MarkupPostParsingRewriter.swift
index b4321860..7c9ece7e 100644
--- a/Sources/MarkdownText/Parser/Scanners/MarkupPostParsingRewriter.swift
+++ b/Sources/MarkdownText/Parser/Scanners/MarkupPostParsingRewriter.swift
@@ -52,6 +52,18 @@ final class PartialTableMarkupPostParsingRewriter: MarkupPostParsingRewriter {
   }
 }
 
+/// Rewrites supported inline raw-HTML tags into Markdown equivalents. See
+/// `InlineHTMLRewriter`. Runs unconditionally: it only touches subtrees that
+/// contain `InlineHTML` nodes and is not a speculative repair.
+final class InlineHTMLMarkupPostParsingRewriter: MarkupPostParsingRewriter {
+
+  func rewriteIfApplicable(document: Document) -> Document? {
+    guard InlineHTMLRewriter.containsInlineHTML(document) else { return nil }
+    var rewriter = InlineHTMLRewriter()
+    return rewriter.visit(document) as? Document
+  }
+}
+
 /// Splits paragraphs that contain images into block-level image-only
 /// paragraphs. See `ImageBlockRewriter`.
 ///
diff --git a/Sources/MarkdownText/Utilities/MDFont.swift b/Sources/MarkdownText/Utilities/MDFont.swift
index 679963b8..b6990eb5 100644
--- a/Sources/MarkdownText/Utilities/MDFont.swift
+++ b/Sources/MarkdownText/Utilities/MDFont.swift
@@ -12,3 +12,14 @@ import AppKit
 /// Cross-platform font type. Resolves to `UIFont` on UIKit platforms and `NSFont` on AppKit platforms.
 public typealias MDFont = NSFont
 #endif
+
+extension MDFont {
+  /// Returns a copy of the font scaled by `factor`.
+  func scaled(by factor: CGFloat) -> MDFont {
+    #if canImport(UIKit)
+    return withSize(pointSize * factor)
+    #else
+    return NSFont(descriptor: fontDescriptor, size: pointSize * factor) ?? self
+    #endif
+  }
+}
diff --git a/Tests/MarkdownTextTests/InlineHTMLRewriterTests.swift b/Tests/MarkdownTextTests/InlineHTMLRewriterTests.swift
new file mode 100644
index 00000000..d49381c1
--- /dev/null
+++ b/Tests/MarkdownTextTests/InlineHTMLRewriterTests.swift
@@ -0,0 +1,146 @@
+//
+//  Copyright (c) Microsoft Corporation. All rights reserved.
+//  Licensed under the MIT License. See LICENSE in the project root for license information.
+//
+
+@testable import SwiftStreamingMarkdown
+import Markdown
+import XCTest
+
+final class InlineHTMLRewriterTests: XCTestCase {
+
+  private let parser = MarkdownParserImpl()
+
+  /// Parses `text` through the full pipeline and returns the rendered
+  /// paragraph's attributed content.
+  private func renderedParagraph(_ text: String) async -> NSMutableAttributedString? {
+    let renderables = await renderables(text)
+    guard case .paragraph(_, let content) = renderables.first else { return nil }
+    return content
+  }
+
+  private func renderables(_ text: String) async -> [MarkdownRenderable] {
+    await parser.parse(text: text, config: .default).renderables
+  }
+
+  // MARK: - Inline containers
+
+  func test_bold_tag_renders_strong() async {
+    let content = await renderedParagraph("a <b>bold</b> c")
+    XCTAssertEqual(content?.string, "a bold c")
+    let boldFont = content?.attribute(.font, at: 2, effectiveRange: nil) as? MDFont
+    let plainFont = content?.attribute(.font, at: 0, effectiveRange: nil) as? MDFont
+    XCTAssertNotNil(boldFont)
+    XCTAssertNotEqual(boldFont, plainFont)
+  }
+
+  func test_italic_tag_renders_emphasis() async {
+    let content = await renderedParagraph("a <i>x</i>")
+    XCTAssertEqual(content?.string, "a x")
+  }
+
+  func test_strikethrough_tag_adds_strike_attribute() async {
+    let content = await renderedParagraph("a <s>gone</s>")
+    XCTAssertEqual(content?.string, "a gone")
+    let strike = content?.attribute(.strikethroughStyle, at: 2, effectiveRange: nil) as? Int
+    XCTAssertEqual(strike, NSUnderlineStyle.single.rawValue)
+  }
+
+  func test_br_tag_renders_line_break() async {
+    let content = await renderedParagraph("one<br>two")
+    XCTAssertEqual(content?.string, "one\ntwo")
+  }
+
+  func test_kbd_tag_renders_inline_code() async {
+    let content = await renderedParagraph("press <kbd>Cmd</kbd>")
+    XCTAssertEqual(content?.string, "press Cmd")
+    let background = content?.attribute(.backgroundColor, at: 6, effectiveRange: nil)
+    XCTAssertNotNil(background)
+  }
+
+  func test_sub_and_sup_tags_set_baseline_offsets() async {
+    let content = await renderedParagraph("H<sub>2</sub>O x<sup>2</sup>")
+    XCTAssertEqual(content?.string, "H2O x2")
+    let sub = content?.attribute(.baselineOffset, at: 1, effectiveRange: nil) as? CGFloat
+    XCTAssertNotNil(sub)
+    XCTAssertLessThan(sub ?? 0, 0)
+    let sup = content?.attribute(.baselineOffset, at: 5, effectiveRange: nil) as? CGFloat
+    XCTAssertNotNil(sup)
+    XCTAssertGreaterThan(sup ?? 0, 0)
+  }
+
+  func test_u_tag_underlines() async {
+    let content = await renderedParagraph("a <u>under</u>")
+    let underline = content?.attribute(.underlineStyle, at: 2, effectiveRange: nil) as? Int
+    XCTAssertEqual(underline, NSUnderlineStyle.single.rawValue)
+  }
+
+  func test_mark_tag_highlights() async {
+    let content = await renderedParagraph("a <mark>hi</mark>")
+    let background = content?.attribute(.backgroundColor, at: 2, effectiveRange: nil) as? MDColor
+    XCTAssertNotNil(background)
+  }
+
+  func test_anchor_tag_renders_link() async {
+    let content = await renderedParagraph("see <a href=\"https://example.com\">site</a>")
+    XCTAssertEqual(content?.string, "see site")
+    let link = content?.attribute(.link, at: 4, effectiveRange: nil) as? URL
+    XCTAssertEqual(link?.absoluteString, "https://example.com")
+  }
+
+  func test_nested_attribute_tags_compose() async {
+    let content = await renderedParagraph("a <u><sup>x</sup></u>")
+    let underline = content?.attribute(.underlineStyle, at: 2, effectiveRange: nil) as? Int
+    XCTAssertEqual(underline, NSUnderlineStyle.single.rawValue)
+    let sup = content?.attribute(.baselineOffset, at: 2, effectiveRange: nil) as? CGFloat
+    XCTAssertGreaterThan(sup ?? 0, 0)
+  }
+
+  func test_tag_inside_strong_keeps_bold() async {
+    let content = await renderedParagraph("**<u>x</u>**")
+    XCTAssertEqual(content?.string, "x")
+    let underline = content?.attribute(.underlineStyle, at: 0, effectiveRange: nil) as? Int
+    XCTAssertEqual(underline, NSUnderlineStyle.single.rawValue)
+  }
+
+  // MARK: - Graceful degradation
+
+  func test_unclosed_tag_applies_to_end_of_container() async {
+    let content = await renderedParagraph("a <b>bold")
+    XCTAssertEqual(content?.string, "a bold")
+  }
+
+  func test_stray_close_tag_renders_literally() async {
+    let content = await renderedParagraph("a </b> c")
+    XCTAssertEqual(content?.string, "a </b> c")
+  }
+
+  func test_unknown_tag_renders_literally() async {
+    let content = await renderedParagraph("a <span>x</span> b")
+    XCTAssertEqual(content?.string, "a <span>x</span> b")
+  }
+
+  func test_comment_is_dropped() async {
+    let content = await renderedParagraph("a <!-- hidden --> b")
+    XCTAssertEqual(content?.string, "a  b")
+  }
+
+  func test_anchor_without_href_renders_literally() async {
+    let content = await renderedParagraph("a <a>x</a>")
+    XCTAssertEqual(content?.string, "a <a>x</a>")
+  }
+
+  // MARK: - Non-regression
+
+  func test_document_without_html_is_untouched() async {
+    let renderables = await renderables("plain **bold** text")
+    guard case .paragraph = renderables.first else {
+      return XCTFail("expected paragraph")
+    }
+  }
+
+  func test_html_inside_code_span_is_not_rewritten() async {
+    let content = await renderedParagraph("`<b>x</b>`")
+    XCTAssertEqual(content?.string, "<b>x</b>")
+  }
+}

From 1be71f2849636461a1ffb3fcaa6ffe270acc50d1 Mon Sep 17 00:00:00 2001
From: Vincent Peng <mail@vincentpeng.me>
Date: Fri, 9 Oct 2026 00:01:02 +1100
Subject: [PATCH 2/8] Harden inline HTML rewriting against malformed and
 adversarial input
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-ups from review:

- Bound tag-matching recursion at 64 pairs of nesting; deeper input emits
  literally instead of recursing quadratically / overflowing the stack.
- Convert HTMLBlock nodes (standalone-line tags, cmark block type 7) to
  literal paragraphs so their text is never silently dropped.
- Replace the href regex with a quote-aware scanner: matches only on a
  whitespace boundary (no data-href/xlink:href false positives), skips
  quoted attribute values, and accepts case-insensitive HREF.
- Decode common named/numeric entities in href values (&amp;, &quot;, …).
- Flatten InlineAttributes inside <a> to their children so the link still
  forms; split underline/highlight/sub/sup runs around non-recurring
  children (Link, Image) instead of going fully literal.
- Use InlineCode.code when flattening nested inline code inside <code>.
- Accept the full cmark whitespace set inside tags; map </br> to a line
  break like browsers do.
- Require a key boundary in the InlineAttributes enabled-key regex.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../Inline/Markdown+InlineConvertible.swift   |   2 +-
 .../Parser/Rewriters/InlineHTMLRewriter.swift | 230 ++++++++++++++----
 .../InlineHTMLRewriterTests.swift             |  71 ++++++
 3 files changed, 258 insertions(+), 45 deletions(-)

diff --git a/Sources/MarkdownText/Inline/Markdown+InlineConvertible.swift b/Sources/MarkdownText/Inline/Markdown+InlineConvertible.swift
index ac6e36cc..eac1c963 100644
--- a/Sources/MarkdownText/Inline/Markdown+InlineConvertible.swift
+++ b/Sources/MarkdownText/Inline/Markdown+InlineConvertible.swift
@@ -192,7 +192,7 @@ extension Markdown.InlineAttributes: InlineConvertible {
   /// Attribute keys this renderer understands inside `attributes`. Produced by
   /// `InlineHTMLRewriter` for tags that have no dedicated Markdown node
   /// (`<u>`/`<ins>`, `<mark>`, `<sub>`, `<sup>`).
-  private static let enabledKeyRegex = try? Regex(#"([a-zA-Z]+)\s*:\s*true"#)
+  private static let enabledKeyRegex = try? Regex(#"(?:^|[,{}\s])([a-zA-Z]+)\s*:\s*true"#)
 
   private var enabledKeys: Set<String> {
     guard let regex = Self.enabledKeyRegex else { return [] }
diff --git a/Sources/MarkdownText/Parser/Rewriters/InlineHTMLRewriter.swift b/Sources/MarkdownText/Parser/Rewriters/InlineHTMLRewriter.swift
index b1a75fff..e6e6e66a 100644
--- a/Sources/MarkdownText/Parser/Rewriters/InlineHTMLRewriter.swift
+++ b/Sources/MarkdownText/Parser/Rewriters/InlineHTMLRewriter.swift
@@ -21,8 +21,17 @@ import Markdown
 /// so their source stays visible. An open tag with no matching close applies
 /// to the rest of the inline container (browser-style auto-close), which keeps
 /// streamed documents sensible while a tag is still arriving.
+///
+/// Standalone-line tags are parsed by cmark as `HTMLBlock` rather than
+/// `InlineHTML`; those blocks are converted to literal paragraphs so their
+/// text is never silently dropped.
 final class InlineHTMLRewriter: MarkupRewriter {
 
+  /// Maximum tag-pair nesting depth processed before the remainder of a
+  /// container is emitted literally. Bounds recursion and the per-open
+  /// closing-tag scan on adversarial inputs like thousands of unclosed tags.
+  private static let maxDepth = 64
+
   private enum Tag {
     case open(name: String, attributes: String)
     case close(name: String)
@@ -36,7 +45,15 @@ final class InlineHTMLRewriter: MarkupRewriter {
     "code", "kbd", "samp", "tt", "a"
   ]
 
-  private static let hrefRegex = try? Regex(#"href\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))"#)
+  /// Whitespace cmark accepts inside a tag (`spacechar` in the HTML scanners).
+  private static let htmlWhitespace: Set<Character> = [" ", "\t", "\n", "\r", "\u{0B}", "\u{0C}"]
+
+  /// `HTMLBlock` nodes have no renderable representation; without this they
+  /// would be dropped, losing their text entirely. Render the source verbatim
+  /// so `<details>` and friends degrade to readable text.
+  func visitHTMLBlock(_ htmlBlock: HTMLBlock) -> Markup? {
+    return Paragraph([Text(htmlBlock.rawHTML)])
+  }
 
   func visitParagraph(_ paragraph: Paragraph) -> Markup? { rewriteInlineChildren(paragraph) }
   func visitHeading(_ heading: Heading) -> Markup? { rewriteInlineChildren(heading) }
@@ -61,13 +78,24 @@ final class InlineHTMLRewriter: MarkupRewriter {
     return visited
   }
 
-  /// Whether the subtree contains any `InlineHTML` node. Used to prune
-  /// containers (and whole documents) that need no rewriting.
+  /// Whether the subtree contains any `InlineHTML` or `HTMLBlock` node. Used
+  /// to prune containers (and whole documents) that need no rewriting.
   static func containsInlineHTML(_ markup: Markup) -> Bool {
-    markup.children.contains { $0 is InlineHTML || containsInlineHTML($0) }
+    markup.children.contains {
+      $0 is InlineHTML || $0 is HTMLBlock || containsInlineHTML($0)
+    }
   }
 
-  private func process(_ input: [Markup]) -> [InlineMarkup] {
+  private func process(_ input: [Markup], depth: Int = 0) -> [InlineMarkup] {
+    // At the depth cap, emit everything verbatim: `InlineHTML` becomes literal
+    // text and other nodes pass through. This bounds recursion and the
+    // per-open scan on inputs like thousands of unclosed `<b>` tags.
+    if depth >= Self.maxDepth {
+      return input.compactMap { markup in
+        if let html = markup as? InlineHTML { return Text(html.rawHTML) }
+        return markup as? InlineMarkup
+      }
+    }
     var output: [InlineMarkup] = []
     var index = 0
     while index < input.count {
@@ -81,6 +109,10 @@ final class InlineHTMLRewriter: MarkupRewriter {
       switch classify(html) {
       case .comment:
         index += 1
+      case .close("br"):
+        // `</br>` is a parse error that browsers treat as `<br>`.
+        output.append(LineBreak())
+        index += 1
       case .other, .close:
         output.append(Text(html.rawHTML))
         index += 1
@@ -101,23 +133,12 @@ final class InlineHTMLRewriter: MarkupRewriter {
           continue
         }
         if let closeIndex = findClosingIndex(named: name, in: input, from: index + 1) {
-          let inner = process(Array(input[(index + 1)..<closeIndex]))
-          if let wrapped = wrapPair(name: name, attributes: attributes, inner: inner) {
-            output.append(wrapped)
-          } else {
-            output.append(Text(html.rawHTML))
-            output.append(contentsOf: inner)
-            output.append(Text((input[closeIndex] as? InlineHTML)?.rawHTML ?? ""))
-          }
+          let inner = process(Array(input[(index + 1)..<closeIndex]), depth: depth + 1)
+          output.append(contentsOf: wrapOrLiteral(open: html, close: input[closeIndex], name: name, attributes: attributes, inner: inner))
           index = closeIndex + 1
         } else {
-          let inner = process(Array(input[(index + 1)...]))
-          if let wrapped = wrapPair(name: name, attributes: attributes, inner: inner) {
-            output.append(wrapped)
-          } else {
-            output.append(Text(html.rawHTML))
-            output.append(contentsOf: inner)
-          }
+          let inner = process(Array(input[(index + 1)...]), depth: depth + 1)
+          output.append(contentsOf: wrapOrLiteral(open: html, close: nil, name: name, attributes: attributes, inner: inner))
           index = input.count
         }
       }
@@ -125,6 +146,20 @@ final class InlineHTMLRewriter: MarkupRewriter {
     return output
   }
 
+  /// Returns the wrapped pair, or the literal open tag + inner nodes + literal
+  /// close tag when the pair can't be represented.
+  private func wrapOrLiteral(open: InlineHTML, close: Markup?, name: String, attributes: String, inner: [InlineMarkup]) -> [InlineMarkup] {
+    if let wrapped = wrapPair(name: name, attributes: attributes, inner: inner) {
+      return wrapped
+    }
+    var literal: [InlineMarkup] = [Text(open.rawHTML)]
+    literal.append(contentsOf: inner)
+    if let close = close as? InlineHTML {
+      literal.append(Text(close.rawHTML))
+    }
+    return literal
+  }
+
   private func classify(_ html: InlineHTML) -> Tag {
     let raw = html.rawHTML.trimmingCharacters(in: .whitespaces)
     if raw.hasPrefix("<!--") { return .comment }
@@ -132,13 +167,13 @@ final class InlineHTMLRewriter: MarkupRewriter {
     var inner = String(raw.dropFirst().dropLast())
     if inner.hasPrefix("/") {
       inner.removeFirst()
-      let name = inner.split(whereSeparator: { $0 == " " || $0 == "\t" || $0 == "/" }).first.map(String.init) ?? ""
+      let name = inner.split(whereSeparator: { Self.htmlWhitespace.contains($0) || $0 == "/" }).first.map(String.init) ?? ""
       return name.first?.isLetter == true ? .close(name: name.lowercased()) : .other
     }
     // A trailing "/" does not close non-void elements in HTML5, so `<b/>x`
     // behaves like `<b>x`; the tag is still treated as an open.
     if inner.hasSuffix("/") { inner = String(inner.dropLast()) }
-    guard let nameEnd = inner.firstIndex(where: { $0 == " " || $0 == "\t" || $0 == "\n" }) else {
+    guard let nameEnd = inner.firstIndex(where: { Self.htmlWhitespace.contains($0) }) else {
       let name = inner.lowercased()
       return name.first?.isLetter == true ? .open(name: name, attributes: "") : .other
     }
@@ -170,14 +205,14 @@ final class InlineHTMLRewriter: MarkupRewriter {
 
   /// Wraps the processed children of a matched tag pair, or returns `nil` when
   /// the pair cannot be represented (the caller then renders it literally).
-  private func wrapPair(name: String, attributes: String, inner: [InlineMarkup]) -> InlineMarkup? {
+  private func wrapPair(name: String, attributes: String, inner: [InlineMarkup]) -> [InlineMarkup]? {
     switch name {
     case "b", "strong":
-      return Strong(inner)
+      return [Strong(inner)]
     case "i", "em":
-      return Emphasis(inner)
+      return [Emphasis(inner)]
     case "s", "del", "strike":
-      return Strikethrough(inner)
+      return [Strikethrough(inner)]
     case "u", "ins":
       return attributeWrap("underline", inner)
     case "mark":
@@ -187,46 +222,153 @@ final class InlineHTMLRewriter: MarkupRewriter {
     case "sup":
       return attributeWrap("superscript", inner)
     case "code", "kbd", "samp", "tt":
-      return InlineCode(inner.map { $0.plainText }.joined())
+      return [InlineCode(inner.map { ($0 as? InlineCode)?.code ?? $0.plainText }.joined())]
     case "a":
       guard let href = hrefValue(in: attributes),
-            let children = recurring(inner) else { return nil }
-      return Link(destination: href, children)
+            let children = linkChildren(inner) else { return nil }
+      return [Link(destination: href, children)]
     default:
       return nil
     }
   }
 
-  /// `InlineAttributes` children must be `RecurringInlineMarkup`, so stacked
-  /// attribute tags (`<u><sup>x</sup></u>`) compose by merging keys into a
-  /// single node. A non-recurring child makes the pair render literally.
-  private func attributeWrap(_ key: String, _ inner: [InlineMarkup]) -> InlineMarkup? {
-    if inner.count == 1, let nested = inner.first as? InlineAttributes {
-      let children = Array(nested.children).compactMap { $0 as? (any RecurringInlineMarkup) }
-      guard children.count == nested.childCount else { return nil }
-      return InlineAttributes(attributes: mergedAttributes(nested.attributes, key: key), children)
+  /// `InlineAttributes` children must be `RecurringInlineMarkup`. Stacked
+  /// attribute tags (`<u><sup>x</sup></u>`) merge into a single node; other
+  /// non-recurring children (`Link`, `Image`) split the attribute run so the
+  /// surrounding text still gets the style instead of the whole pair going
+  /// literal.
+  private func attributeWrap(_ key: String, _ inner: [InlineMarkup]) -> [InlineMarkup] {
+    var output: [InlineMarkup] = []
+    var run: [any RecurringInlineMarkup] = []
+
+    func flushRun() {
+      guard !run.isEmpty else { return }
+      output.append(InlineAttributes(attributes: "{\(key):true}", run))
+      run = []
     }
-    guard let children = recurring(inner) else { return nil }
-    return InlineAttributes(attributes: "{\(key):true}", children)
+
+    for markup in inner {
+      if let attributes = markup as? InlineAttributes {
+        // Nested attribute tags merge keys: `<u><sup>x</sup></u>` keeps both
+        // underline and superscript. Children that can't rebuild the node
+        // degrade to the unmerged original.
+        flushRun()
+        if let children = recurring(Array(attributes.children)) {
+          output.append(InlineAttributes(attributes: mergedAttributes(attributes.attributes, key: key), children))
+        } else {
+          output.append(attributes)
+        }
+      } else if let recurring = markup as? (any RecurringInlineMarkup) {
+        run.append(recurring)
+      } else {
+        // Non-recurring nodes (`Link`, `Image`) end the run but stay in the
+        // output, so `<u>text <a>x</a> more</u>` underlines both text parts.
+        flushRun()
+        output.append(markup)
+      }
+    }
+    flushRun()
+    return output
   }
 
+  /// Attributes produced by this rewriter always end in `}`; attribute nodes
+  /// from other sources keep their original string, dropping the new key —
+  /// graceful degradation rather than a malformed merge.
   private func mergedAttributes(_ attributes: String, key: String) -> String {
     guard attributes.hasSuffix("}") else { return attributes }
     return String(attributes.dropLast()) + ",\(key):true}"
   }
 
-  private func recurring(_ inner: [InlineMarkup]) -> [any RecurringInlineMarkup]? {
+  /// `Link` children must be `RecurringInlineMarkup`; `InlineAttributes` nodes
+  /// inside an anchor are flattened to their children (the link wins over the
+  /// inner styling, which is the more useful behavior).
+  private func linkChildren(_ inner: [InlineMarkup]) -> [any RecurringInlineMarkup]? {
+    var children: [any RecurringInlineMarkup] = []
+    for markup in inner {
+      if let attributes = markup as? InlineAttributes {
+        guard let nested = recurring(Array(attributes.children)) else { return nil }
+        children.append(contentsOf: nested)
+      } else if let recurring = markup as? (any RecurringInlineMarkup) {
+        children.append(recurring)
+      } else {
+        return nil
+      }
+    }
+    return children
+  }
+
+  private func recurring(_ inner: [Markup]) -> [any RecurringInlineMarkup]? {
     let children = inner.compactMap { $0 as? (any RecurringInlineMarkup) }
     return children.count == inner.count ? children : nil
   }
 
+  /// Extracts the `href` value from a tag's attribute string with a
+  /// quote-aware scan: attribute names are matched case-insensitively on a
+  /// whitespace boundary, and quoted values are skipped rather than scanned,
+  /// so `data-href` or `title="a href='b'"` can't produce a link.
   private func hrefValue(in attributes: String) -> String? {
-    guard let regex = Self.hrefRegex, let match = attributes.firstMatch(of: regex) else { return nil }
-    for index in 1...3 {
-      if let substring = match.output[index].substring {
-        return String(substring)
+    var index = attributes.startIndex
+    var previousWasBoundary = true
+    while index < attributes.endIndex {
+      let character = attributes[index]
+      if character == "\"" || character == "'" {
+        // Skip a quoted attribute value entirely.
+        index = attributes[index...].dropFirst().firstIndex(of: character) ?? attributes.endIndex
+        if index < attributes.endIndex { index = attributes.index(after: index) }
+        previousWasBoundary = false
+        continue
+      }
+      defer { index = attributes.index(after: index) }
+      if character == "h" || character == "H", previousWasBoundary {
+        let rest = attributes[index...]
+        if rest.count >= 4, rest.prefix(4).lowercased() == "href" {
+          var cursor = rest.index(rest.startIndex, offsetBy: 4)
+          while cursor < attributes.endIndex, Self.htmlWhitespace.contains(attributes[cursor]) {
+            cursor = attributes.index(after: cursor)
+          }
+          if cursor < attributes.endIndex, attributes[cursor] == "=" {
+            cursor = attributes.index(after: cursor)
+            while cursor < attributes.endIndex, Self.htmlWhitespace.contains(attributes[cursor]) {
+              cursor = attributes.index(after: cursor)
+            }
+            return decodeEntities(attributeValue(in: attributes, from: &cursor))
+          }
+        }
       }
+      previousWasBoundary = Self.htmlWhitespace.contains(character)
     }
     return nil
   }
+
+  /// Reads one attribute value: quoted, or unquoted until whitespace/`>`.
+  private func attributeValue(in attributes: String, from cursor: inout String.Index) -> String {
+    guard cursor < attributes.endIndex else { return "" }
+    let quote = attributes[cursor]
+    if quote == "\"" || quote == "'" {
+      let valueStart = attributes.index(after: cursor)
+      let valueEnd = attributes[valueStart...].firstIndex(of: quote) ?? attributes.endIndex
+      cursor = valueEnd < attributes.endIndex ? attributes.index(after: valueEnd) : attributes.endIndex
+      return String(attributes[valueStart..<valueEnd])
+    }
+    var end = cursor
+    while end < attributes.endIndex, !Self.htmlWhitespace.contains(attributes[end]), attributes[end] != ">" {
+      end = attributes.index(after: end)
+    }
+    defer { cursor = end }
+    return String(attributes[cursor..<end])
+  }
+
+  /// Decodes the common named and numeric entities found in attribute values
+  /// (cmark decodes `Text` nodes but never sees attribute contents).
+  private func decodeEntities(_ value: String) -> String {
+    guard value.contains("&") else { return value }
+    var result = value
+    result = result.replacingOccurrences(of: "&quot;", with: "\"")
+    result = result.replacingOccurrences(of: "&#39;", with: "'")
+    result = result.replacingOccurrences(of: "&#x27;", with: "'")
+    result = result.replacingOccurrences(of: "&lt;", with: "<")
+    result = result.replacingOccurrences(of: "&gt;", with: ">")
+    result = result.replacingOccurrences(of: "&amp;", with: "&")
+    return result
+  }
 }
diff --git a/Tests/MarkdownTextTests/InlineHTMLRewriterTests.swift b/Tests/MarkdownTextTests/InlineHTMLRewriterTests.swift
index d49381c1..4caedb3e 100644
--- a/Tests/MarkdownTextTests/InlineHTMLRewriterTests.swift
+++ b/Tests/MarkdownTextTests/InlineHTMLRewriterTests.swift
@@ -130,6 +130,77 @@ final class InlineHTMLRewriterTests: XCTestCase {
     XCTAssertEqual(content?.string, "a <a>x</a>")
   }
 
+  func test_data_href_does_not_produce_a_link() async {
+    let content = await renderedParagraph("a <a data-href=\"https://evil.example\">x</a>")
+    XCTAssertEqual(content?.string, "a <a data-href=\"https://evil.example\">x</a>")
+    let link = content?.attribute(.link, at: 2, effectiveRange: nil)
+    XCTAssertNil(link)
+  }
+
+  func test_uppercase_href_produces_link() async {
+    let content = await renderedParagraph("a <a HREF=\"https://example.com\">x</a>")
+    XCTAssertEqual(content?.string, "a x")
+    let link = content?.attribute(.link, at: 2, effectiveRange: nil) as? URL
+    XCTAssertEqual(link?.absoluteString, "https://example.com")
+  }
+
+  func test_quoted_attribute_containing_href_is_skipped() async {
+    let content = await renderedParagraph("a <a title=\"v href='x'\" href=\"https://real.example\">x</a>")
+    let link = content?.attribute(.link, at: 2, effectiveRange: nil) as? URL
+    XCTAssertEqual(link?.absoluteString, "https://real.example")
+  }
+
+  func test_href_entities_are_decoded() async {
+    let content = await renderedParagraph("a <a href=\"https://x.example?a=1&amp;b=2\">x</a>")
+    let link = content?.attribute(.link, at: 2, effectiveRange: nil) as? URL
+    XCTAssertEqual(link?.absoluteString, "https://x.example?a=1&b=2")
+  }
+
+  func test_stray_br_close_tag_renders_line_break() async {
+    let content = await renderedParagraph("a</br>b")
+    XCTAssertEqual(content?.string, "a\nb")
+  }
+
+  func test_standalone_tag_block_renders_literally() async {
+    // `<b>` on its own line is an HTML block (cmark type 7); it must not lose text.
+    let renderables = await renderables("intro\n\n<b>\nHello world\n</b>\n\noutro")
+    let allText = renderables.compactMap { renderable -> String? in
+      guard case .paragraph(_, let content) = renderable else { return nil }
+      return content.string
+    }.joined()
+    XCTAssertTrue(allText.contains("Hello world"))
+    XCTAssertTrue(allText.contains("intro"))
+  }
+
+  func test_underline_wraps_text_around_a_link() async {
+    let content = await renderedParagraph("<u>before <a href=\"https://x.example\">mid</a> after</u>")
+    XCTAssertEqual(content?.string, "before mid after")
+    let underlineBefore = content?.attribute(.underlineStyle, at: 0, effectiveRange: nil) as? Int
+    XCTAssertEqual(underlineBefore, NSUnderlineStyle.single.rawValue)
+    let link = content?.attribute(.link, at: 7, effectiveRange: nil) as? URL
+    XCTAssertEqual(link?.absoluteString, "https://x.example")
+    let underlineAfter = content?.attribute(.underlineStyle, at: 10, effectiveRange: nil) as? Int
+    XCTAssertEqual(underlineAfter, NSUnderlineStyle.single.rawValue)
+  }
+
+  func test_link_wraps_attribute_styled_text() async {
+    let content = await renderedParagraph("<a href=\"https://x.example\"><u>x</u></a>")
+    XCTAssertEqual(content?.string, "x")
+    let link = content?.attribute(.link, at: 0, effectiveRange: nil) as? URL
+    XCTAssertEqual(link?.absoluteString, "https://x.example")
+  }
+
+  func test_code_tag_flattens_nested_inline_code() async {
+    let content = await renderedParagraph("<code>a `b` c</code>")
+    XCTAssertEqual(content?.string, "a b c")
+  }
+
+  func test_deeply_unclosed_tags_do_not_crash() async {
+    let opens = String(repeating: "<b>", count: 500)
+    let content = await renderedParagraph("a \(opens)x")
+    XCTAssertNotNil(content?.string)
+  }
+
   // MARK: - Non-regression
 
   func test_document_without_html_is_untouched() async {

From 6873ea98bfa97e11aaf6ac940402a6da5eadca28 Mon Sep 17 00:00:00 2001
From: Vincent Peng <mail@vincentpeng.me>
Date: Fri, 9 Oct 2026 00:37:53 +1100
Subject: [PATCH 3/8] Fix second-round review findings in inline HTML rewriting
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- visitHTMLBlock now drops comment/PI/declaration blocks instead of
  surfacing them as visible text, matching inline comment handling.
- Images inside <b>/<i>/<s> wrappers split the run so Image nodes reach
  paragraph level where ImageBlockRewriter can hoist them — previously
  an image inside a bold tag was silently dropped at conversion.
- Link/Image/InlineAttributes children are filtered back to
  RecurringInlineMarkup (text-preserved fallback) so rewritten content
  stays within swift-markdown's structural rules.
- Depth-cap fallback path now drops comments consistently.
- enabledKey regex requires a word boundary after 'true'; README lists
  <strike> and clarifies comment handling.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 README.md                                     |  2 +-
 .../Inline/Markdown+InlineConvertible.swift   |  2 +-
 .../Parser/Rewriters/InlineHTMLRewriter.swift | 50 ++++++++++++++++---
 .../InlineHTMLRewriterTests.swift             | 28 +++++++++++
 4 files changed, 72 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index ab3cb1f2..91e9e6f6 100644
--- a/README.md
+++ b/README.md
@@ -113,7 +113,7 @@ The renderer targets the subset of CommonMark + GitHub-flavored Markdown that LL
 - [x] Inline LaTeX math via `\( … \)`
 - [x] Display LaTeX math via `$$ … $$`
 - [x] Inline citation pills
-- [x] Inline HTML formatting tags — `<br>`, `<b>`/`<strong>`, `<i>`/`<em>`, `<s>`/`<del>`, `<u>`/`<ins>`, `<mark>`, `<sub>`/`<sup>`, `<code>`/`<kbd>`/`<samp>`/`<tt>`, `<a href>`, `<wbr>` (unmatched or unsupported tags render as literal text)
+- [x] Inline HTML formatting tags — `<br>`, `<b>`/`<strong>`, `<i>`/`<em>`, `<s>`/`<del>`/`<strike>`, `<u>`/`<ins>`, `<mark>`, `<sub>`/`<sup>`, `<code>`/`<kbd>`/`<samp>`/`<tt>`, `<a href>`, `<wbr>` (comments are dropped; unsupported or unmatched tags render as literal text)
 
 ### Not yet supported
 
diff --git a/Sources/MarkdownText/Inline/Markdown+InlineConvertible.swift b/Sources/MarkdownText/Inline/Markdown+InlineConvertible.swift
index eac1c963..b82d16a4 100644
--- a/Sources/MarkdownText/Inline/Markdown+InlineConvertible.swift
+++ b/Sources/MarkdownText/Inline/Markdown+InlineConvertible.swift
@@ -192,7 +192,7 @@ extension Markdown.InlineAttributes: InlineConvertible {
   /// Attribute keys this renderer understands inside `attributes`. Produced by
   /// `InlineHTMLRewriter` for tags that have no dedicated Markdown node
   /// (`<u>`/`<ins>`, `<mark>`, `<sub>`, `<sup>`).
-  private static let enabledKeyRegex = try? Regex(#"(?:^|[,{}\s])([a-zA-Z]+)\s*:\s*true"#)
+  private static let enabledKeyRegex = try? Regex(#"(?:^|[,{}\s])([a-zA-Z]+)\s*:\s*true\b"#)
 
   private var enabledKeys: Set<String> {
     guard let regex = Self.enabledKeyRegex else { return [] }
diff --git a/Sources/MarkdownText/Parser/Rewriters/InlineHTMLRewriter.swift b/Sources/MarkdownText/Parser/Rewriters/InlineHTMLRewriter.swift
index e6e6e66a..5c867293 100644
--- a/Sources/MarkdownText/Parser/Rewriters/InlineHTMLRewriter.swift
+++ b/Sources/MarkdownText/Parser/Rewriters/InlineHTMLRewriter.swift
@@ -50,8 +50,14 @@ final class InlineHTMLRewriter: MarkupRewriter {
 
   /// `HTMLBlock` nodes have no renderable representation; without this they
   /// would be dropped, losing their text entirely. Render the source verbatim
-  /// so `<details>` and friends degrade to readable text.
+  /// so `<details>` and friends degrade to readable text. Comments,
+  /// processing instructions, and declarations are dropped like their inline
+  /// counterparts rather than surfacing as visible text.
   func visitHTMLBlock(_ htmlBlock: HTMLBlock) -> Markup? {
+    let raw = htmlBlock.rawHTML.trimmingCharacters(in: .whitespacesAndNewlines)
+    if raw.hasPrefix("<!--") || raw.hasPrefix("<?") || raw.hasPrefix("<!") {
+      return nil
+    }
     return Paragraph([Text(htmlBlock.rawHTML)])
   }
 
@@ -74,7 +80,13 @@ final class InlineHTMLRewriter: MarkupRewriter {
     // it must be called through a variable; `self` is a class reference here.
     var mutableSelf = self
     guard var visited = mutableSelf.defaultVisit(container) as? Container else { return container }
-    visited.setInlineChildren(process(Array(visited.children)))
+    var children = process(Array(visited.children))
+    // `Link`, `Image`, and `InlineAttributes` only allow `RecurringInlineMarkup`
+    // children; degraded nodes keep their text as a literal fallback.
+    if visited is Link || visited is Image || visited is InlineAttributes {
+      children = children.map { $0 as? (any RecurringInlineMarkup) ?? Text($0.plainText) }
+    }
+    visited.setInlineChildren(children)
     return visited
   }
 
@@ -92,8 +104,9 @@ final class InlineHTMLRewriter: MarkupRewriter {
     // per-open scan on inputs like thousands of unclosed `<b>` tags.
     if depth >= Self.maxDepth {
       return input.compactMap { markup in
-        if let html = markup as? InlineHTML { return Text(html.rawHTML) }
-        return markup as? InlineMarkup
+        guard let html = markup as? InlineHTML else { return markup as? InlineMarkup }
+        if case .comment = classify(html) { return nil }
+        return Text(html.rawHTML)
       }
     }
     var output: [InlineMarkup] = []
@@ -208,11 +221,11 @@ final class InlineHTMLRewriter: MarkupRewriter {
   private func wrapPair(name: String, attributes: String, inner: [InlineMarkup]) -> [InlineMarkup]? {
     switch name {
     case "b", "strong":
-      return [Strong(inner)]
+      return splitOnImages(inner) { Strong($0) }
     case "i", "em":
-      return [Emphasis(inner)]
+      return splitOnImages(inner) { Emphasis($0) }
     case "s", "del", "strike":
-      return [Strikethrough(inner)]
+      return splitOnImages(inner) { Strikethrough($0) }
     case "u", "ins":
       return attributeWrap("underline", inner)
     case "mark":
@@ -232,6 +245,27 @@ final class InlineHTMLRewriter: MarkupRewriter {
     }
   }
 
+  /// Splits a basic wrapper run around `Image` children: images must reach
+  /// paragraph level for `ImageBlockRewriter` to hoist them into blocks —
+  /// an `Image` nested inside `Strong` would be dropped at conversion.
+  private func splitOnImages(_ inner: [InlineMarkup], wrap: ([InlineMarkup]) -> InlineMarkup) -> [InlineMarkup] {
+    var output: [InlineMarkup] = []
+    var run: [InlineMarkup] = []
+    for markup in inner {
+      if markup is Image {
+        if !run.isEmpty {
+          output.append(wrap(run))
+          run = []
+        }
+        output.append(markup)
+      } else {
+        run.append(markup)
+      }
+    }
+    if !run.isEmpty { output.append(wrap(run)) }
+    return output
+  }
+
   /// `InlineAttributes` children must be `RecurringInlineMarkup`. Stacked
   /// attribute tags (`<u><sup>x</sup></u>`) merge into a single node; other
   /// non-recurring children (`Link`, `Image`) split the attribute run so the
@@ -321,7 +355,7 @@ final class InlineHTMLRewriter: MarkupRewriter {
       defer { index = attributes.index(after: index) }
       if character == "h" || character == "H", previousWasBoundary {
         let rest = attributes[index...]
-        if rest.count >= 4, rest.prefix(4).lowercased() == "href" {
+        if rest.prefix(4).lowercased() == "href" {
           var cursor = rest.index(rest.startIndex, offsetBy: 4)
           while cursor < attributes.endIndex, Self.htmlWhitespace.contains(attributes[cursor]) {
             cursor = attributes.index(after: cursor)
diff --git a/Tests/MarkdownTextTests/InlineHTMLRewriterTests.swift b/Tests/MarkdownTextTests/InlineHTMLRewriterTests.swift
index 4caedb3e..a4408b78 100644
--- a/Tests/MarkdownTextTests/InlineHTMLRewriterTests.swift
+++ b/Tests/MarkdownTextTests/InlineHTMLRewriterTests.swift
@@ -195,6 +195,34 @@ final class InlineHTMLRewriterTests: XCTestCase {
     XCTAssertEqual(content?.string, "a b c")
   }
 
+  func test_block_comment_is_dropped() async {
+    let renderables = await renderables("intro\n\n<!-- note -->\n\noutro")
+    let allText = renderables.compactMap { renderable -> String? in
+      guard case .paragraph(_, let content) = renderable else { return nil }
+      return content.string
+    }.joined()
+    XCTAssertFalse(allText.contains("note"))
+    XCTAssertTrue(allText.contains("intro"))
+    XCTAssertTrue(allText.contains("outro"))
+  }
+
+  func test_image_inside_bold_tag_stays_at_paragraph_level() async {
+    // With image support enabled, `![x](u)` inside `<b>` must not be swallowed.
+    let document = await parser.parse(
+      text: "a <b>![alt](https://x.example/i.png) after</b>",
+      config: .default.withImageConfig(ImageConfig(enabled: true, allowedImageTypes: [.remote(allowedDomains: [])]))
+    )
+    XCTAssertTrue(document.renderables.contains { renderable in
+      if case .image = renderable { return true }
+      return false
+    })
+  }
+
+  func test_nested_link_inside_link_loses_inner_link_keeps_text() async {
+    let content = await renderedParagraph("[a <a href=\"https://inner.example\">inner</a>](https://outer.example)")
+    XCTAssertEqual(content?.string, "a inner")
+  }
+
   func test_deeply_unclosed_tags_do_not_crash() async {
     let opens = String(repeating: "<b>", count: 500)
     let content = await renderedParagraph("a \(opens)x")

From 2d6924d99ca490eeff1eb4e3be3d391a75940ea0 Mon Sep 17 00:00:00 2001
From: Vincent Peng <mail@vincentpeng.me>
Date: Fri, 9 Oct 2026 01:12:21 +1100
Subject: [PATCH 4/8] Render ==highlight== via delimiter pairing rewriter
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds InlineDelimiterRewriter, a spec-driven post-parse pass that pairs
'==' runs in Text nodes using markdown-it-mark flanking rules and wraps
matched ranges in InlineAttributes (already rendered with a highlight
background). Pairing spans sibling inlines so '==**b**==' works, nested
pairs fold into the outer highlight, and unpaired markers stay literal
— important for streamed documents where a closer may still be
arriving. Link/Image/InlineAttributes containers are left alone to
preserve their RecurringInlineMarkup invariants.

Stacked on the inline-HTML branch for the InlineAttributes renderer.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 README.md                                     |   3 +-
 .../Parser/MarkdownParserImpl.swift           |   9 +
 .../Rewriters/InlineDelimiterRewriter.swift   | 299 ++++++++++++++++++
 .../Scanners/MarkupPostParsingRewriter.swift  |  15 +
 .../InlineDelimiterRewriterTests.swift        | 175 ++++++++++
 5 files changed, 500 insertions(+), 1 deletion(-)
 create mode 100644 Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift
 create mode 100644 Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift

diff --git a/README.md b/README.md
index 91e9e6f6..1278860d 100644
--- a/README.md
+++ b/README.md
@@ -114,11 +114,12 @@ The renderer targets the subset of CommonMark + GitHub-flavored Markdown that LL
 - [x] Display LaTeX math via `$$ … $$`
 - [x] Inline citation pills
 - [x] Inline HTML formatting tags — `<br>`, `<b>`/`<strong>`, `<i>`/`<em>`, `<s>`/`<del>`/`<strike>`, `<u>`/`<ins>`, `<mark>`, `<sub>`/`<sup>`, `<code>`/`<kbd>`/`<samp>`/`<tt>`, `<a href>`, `<wbr>` (comments are dropped; unsupported or unmatched tags render as literal text)
+- [x] Highlight (`==text==`)
 
 ### Not yet supported
 
 - [ ] Footnotes (`[^1]`)
-- [ ] Highlight (`==text==`), superscript (`^x^`), subscript (`~x~`)
+- [ ] Superscript (`^x^`), subscript (`~x~`)
 - [ ] Block-level raw HTML (`<details>`, `<aside>`, …) — kept inline as text
 - [ ] GitHub alerts (`> [!NOTE]`) — rendered as plain block quotes
 - [ ] Container directives (`::: warning … :::`) and admonitions (`!!! note`)
diff --git a/Sources/MarkdownText/Parser/MarkdownParserImpl.swift b/Sources/MarkdownText/Parser/MarkdownParserImpl.swift
index 8b22cc60..5b120a61 100644
--- a/Sources/MarkdownText/Parser/MarkdownParserImpl.swift
+++ b/Sources/MarkdownText/Parser/MarkdownParserImpl.swift
@@ -15,6 +15,8 @@ public final class MarkdownParserImpl: MarkdownParser {
 
   private let inlineHTMLRewriter = InlineHTMLMarkupPostParsingRewriter()
 
+  private let delimiterRewriter = InlineDelimiterMarkupPostParsingRewriter()
+
   private let imageBlockRewriter = ImageBlockMarkupPostParsingRewriter()
 
   private let latexPreprocessor: LaTexPreProcessor
@@ -48,6 +50,13 @@ public final class MarkdownParserImpl: MarkdownParser {
       )
     }
 
+    if let rewrittenDoc = delimiterRewriter.rewriteIfApplicable(document: result.document) {
+      result = MarkdownParseResult(
+        document: rewrittenDoc,
+        speculativeRewritten: result.speculativeRewritten
+      )
+    }
+
     if option.imageSupport {
       if let rewrittenDoc = imageBlockRewriter.rewriteIfApplicable(document: result.document) {
         result = MarkdownParseResult(
diff --git a/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift b/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift
new file mode 100644
index 00000000..041fcdd3
--- /dev/null
+++ b/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift
@@ -0,0 +1,299 @@
+//
+//  Copyright (c) Microsoft Corporation. All rights reserved.
+//  Licensed under the MIT License. See LICENSE in the project root for license information.
+//
+
+import Markdown
+
+/// Rewrites paired inline delimiter runs into `InlineAttributes` nodes so
+/// syntax like `==highlight==` renders instead of staying literal text.
+///
+/// Each `DelimiterSpec` describes one marker. `Text` content is scanned for
+/// maximal runs of the marker's character; a run of length `n` yields
+/// `n % marker.count` literal characters followed by `n / marker.count`
+/// marker tokens, so `===x===` produces `=` + marker + `x` + marker + `=`.
+///
+/// All markers in a run share the run's flanking: a marker can open when a
+/// non-whitespace character follows the run and can close when a
+/// non-whitespace character precedes it. Scanning left to right with an
+/// opener stack pairs each closer with the most recent unmatched opener, so
+/// `====x====` nests and still highlights `x`. Markers that never pair stay
+/// as literal text, which keeps streamed documents sensible while a closing
+/// delimiter is still arriving.
+///
+/// `Link`, `Image`, and `InlineAttributes` containers are visited but never
+/// paired at their own level: their children must stay
+/// `RecurringInlineMarkup`, so `==` there remains literal.
+///
+/// Known limitation: a backslash-escaped `\==` arrives as a literal `=` in
+/// `Text` content because cmark strips the escape during parsing, so
+/// `\==x==` still highlights. The two forms are indistinguishable at this
+/// layer.
+final class InlineDelimiterRewriter: MarkupRewriter {
+
+  /// Describes one inline delimiter pair and the attribute it produces.
+  struct DelimiterSpec {
+    /// The repeated-character marker text, e.g. `"=="`.
+    let marker: String
+    /// The `InlineAttributes` key set to `true` on wrapped content.
+    let attribute: String
+    /// Whether the wrapped range may contain whitespace. `false` keeps the
+    /// markers of a pair like `^a b^` literal.
+    let allowsInnerWhitespace: Bool
+
+    /// `==highlight==`; inner whitespace is allowed.
+    static let highlight = DelimiterSpec(marker: "==", attribute: "highlight", allowsInnerWhitespace: true)
+  }
+
+  /// Maximum nested-pair depth transformed before markers are emitted
+  /// literally. Bounds recursion on adversarial inputs like hundreds of
+  /// nested `====...====` runs.
+  private static let maxDepth = 64
+
+  private let specs: [DelimiterSpec]
+
+  init(specs: [DelimiterSpec]) {
+    self.specs = specs
+  }
+
+  func visitParagraph(_ paragraph: Paragraph) -> Markup? { rewriteInlineChildren(paragraph) }
+  func visitHeading(_ heading: Heading) -> Markup? { rewriteInlineChildren(heading) }
+  func visitTableCell(_ tableCell: Table.Cell) -> Markup? { rewriteInlineChildren(tableCell) }
+  func visitEmphasis(_ emphasis: Emphasis) -> Markup? { rewriteInlineChildren(emphasis) }
+  func visitStrong(_ strong: Strong) -> Markup? { rewriteInlineChildren(strong) }
+  func visitStrikethrough(_ strikethrough: Strikethrough) -> Markup? { rewriteInlineChildren(strikethrough) }
+  func visitLink(_ link: Link) -> Markup? { rewriteInlineChildren(link) }
+  func visitImage(_ image: Image) -> Markup? { rewriteInlineChildren(image) }
+  func visitInlineAttributes(_ attributes: InlineAttributes) -> Markup? { rewriteInlineChildren(attributes) }
+
+  /// A flattened sibling: a literal text fragment, a run remainder that is
+  /// also literal text but carries provenance for flanking and wrap
+  /// boundaries, an opaque non-`Text` node, or one delimiter marker token
+  /// stamped with its run's flanking.
+  private enum Piece {
+    case text(String)
+    case remainder(String)
+    case node(InlineMarkup)
+    case marker(specIndex: Int, canOpen: Bool, canClose: Bool)
+  }
+
+  /// Recursively visits the container's children first, then pairs delimiter
+  /// markers at this level. Containers without a spec marker in any `Text`
+  /// descendant are returned unchanged so untouched subtrees keep identity.
+  private func rewriteInlineChildren<Container: InlineContainer & Markup>(_ container: Container) -> Markup? {
+    guard Self.containsDelimiter(container, specs: specs) else { return container }
+    // `defaultVisit` is `mutating` on the non-class-bound visitor protocol, so
+    // it must be called through a variable; `self` is a class reference here.
+    var mutableSelf = self
+    guard var visited = mutableSelf.defaultVisit(container) as? Container else { return container }
+    // `Link`, `Image`, and `InlineAttributes` only allow `RecurringInlineMarkup`
+    // children, so markers at their level are never consumed; deeper
+    // containers have already been processed by `defaultVisit`.
+    if visited is Link || visited is Image || visited is InlineAttributes {
+      return visited
+    }
+    visited.setInlineChildren(process(Array(visited.children)))
+    return visited
+  }
+
+  /// Whether the subtree contains a `Text` node holding a spec marker. Used
+  /// to prune containers (and whole documents) that need no rewriting.
+  static func containsDelimiter(_ markup: Markup, specs: [DelimiterSpec]) -> Bool {
+    markup.children.contains { child in
+      if let text = child as? Text, specs.contains(where: { text.string.contains($0.marker) }) {
+        return true
+      }
+      return containsDelimiter(child, specs: specs)
+    }
+  }
+
+  /// Pairs the container's direct children. When no marker pair exists the
+  /// input passes through unchanged so untouched subtrees keep identity.
+  private func process(_ input: [Markup]) -> [InlineMarkup] {
+    var pieces = tokenize(input)
+    applyFlanking(&pieces)
+    let closeForOpen = pairedCloses(in: pieces)
+    guard !closeForOpen.isEmpty else {
+      return input.compactMap { $0 as? InlineMarkup }
+    }
+    return emit(pieces, in: 0..<pieces.count, closeForOpen: closeForOpen, depth: 0)
+  }
+
+  /// Splits sibling inline nodes into pieces. `Text` runs of a marker
+  /// character become a `remainder` of `n % marker.count` characters plus
+  /// `n / marker.count` marker tokens; every other node stays opaque.
+  private func tokenize(_ input: [Markup]) -> [Piece] {
+    var pieces: [Piece] = []
+    for child in input {
+      guard let text = child as? Text else {
+        if let inline = child as? InlineMarkup {
+          pieces.append(.node(inline))
+        } else {
+          pieces.append(.text((child as? PlainTextConvertibleMarkup)?.plainText ?? ""))
+        }
+        continue
+      }
+      let string = text.string
+      var index = string.startIndex
+      var literalStart = index
+      while index < string.endIndex {
+        guard let specIndex = specs.firstIndex(where: { $0.marker.first == string[index] }) else {
+          index = string.index(after: index)
+          continue
+        }
+        var runEnd = string.index(after: index)
+        while runEnd < string.endIndex, string[runEnd] == string[index] {
+          runEnd = string.index(after: runEnd)
+        }
+        if literalStart < index {
+          pieces.append(.text(String(string[literalStart..<index])))
+        }
+        let runLength = string.distance(from: index, to: runEnd)
+        let markerLength = specs[specIndex].marker.count
+        let literalCount = runLength % markerLength
+        if literalCount > 0 {
+          pieces.append(.remainder(String(repeating: string[index], count: literalCount)))
+        }
+        for _ in 0..<(runLength / markerLength) {
+          pieces.append(.marker(specIndex: specIndex, canOpen: false, canClose: false))
+        }
+        index = runEnd
+        literalStart = runEnd
+      }
+      if literalStart < string.endIndex {
+        pieces.append(.text(String(string[literalStart...])))
+      }
+    }
+    return pieces
+  }
+
+  /// Computes flanking once per marker run and stamps it onto every token.
+  /// A run's `canOpen` requires a non-whitespace character after the last
+  /// marker; `canClose` requires a non-whitespace character before the run,
+  /// which sits before any `remainder` the run emitted.
+  private func applyFlanking(_ pieces: inout [Piece]) {
+    var index = 0
+    while index < pieces.count {
+      guard case .marker = pieces[index] else {
+        index += 1
+        continue
+      }
+      var runEnd = index + 1
+      while runEnd < pieces.count, case .marker = pieces[runEnd] {
+        runEnd += 1
+      }
+      var runStart = index
+      while runStart > 0, case .remainder = pieces[runStart - 1] {
+        runStart -= 1
+      }
+      let canClose = runStart > 0 && lastCharacter(of: pieces[runStart - 1])?.isWhitespace == false
+      let canOpen = runEnd < pieces.count && firstCharacter(of: pieces[runEnd])?.isWhitespace == false
+      for markerIndex in index..<runEnd {
+        guard case .marker(let specIndex, _, _) = pieces[markerIndex] else { continue }
+        pieces[markerIndex] = .marker(specIndex: specIndex, canOpen: canOpen, canClose: canClose)
+      }
+      index = runEnd
+    }
+  }
+
+  /// Pairs each closer with the most recent unmatched opener of the same
+  /// spec and returns `open index -> close index`. A marker that can both
+  /// open and close prefers closing when an opener exists.
+  private func pairedCloses(in pieces: [Piece]) -> [Int: Int] {
+    var openers: [[Int]] = specs.map { _ in [] }
+    var closeForOpen: [Int: Int] = [:]
+    for (index, piece) in pieces.enumerated() {
+      guard case .marker(let specIndex, let canOpen, let canClose) = piece else { continue }
+      if canClose, let openIndex = openers[specIndex].popLast() {
+        closeForOpen[openIndex] = index
+      } else if canOpen {
+        openers[specIndex].append(index)
+      }
+    }
+    return closeForOpen
+  }
+
+  /// Emits the piece range, wrapping each paired open/close span in an
+  /// `InlineAttributes` node. Pairs nest, so an outer wrap absorbs an inner
+  /// `InlineAttributes` as plain text; unpaired markers become literal text.
+  private func emit(_ pieces: [Piece], in range: Range<Int>, closeForOpen: [Int: Int], depth: Int) -> [InlineMarkup] {
+    var output: [InlineMarkup] = []
+    var index = range.lowerBound
+    while index < range.upperBound {
+      switch pieces[index] {
+      case .text(let string), .remainder(let string):
+        output.append(Text(string))
+        index += 1
+      case .node(let node):
+        output.append(node)
+        index += 1
+      case .marker(let specIndex, _, _):
+        let spec = specs[specIndex]
+        guard let close = closeForOpen[index], depth < Self.maxDepth else {
+          output.append(Text(spec.marker))
+          index += 1
+          continue
+        }
+        // `remainder` pieces at the wrap boundary belong to the consumed
+        // markers' own runs, so they emit outside: `===x===` highlights `x`
+        // and leaves one literal `=` on each side.
+        var innerStart = index + 1
+        var innerEnd = close
+        var leading: [String] = []
+        while innerStart < innerEnd, case .remainder(let string) = pieces[innerStart] {
+          leading.append(string)
+          innerStart += 1
+        }
+        var trailing: [String] = []
+        while innerEnd > innerStart, case .remainder(let string) = pieces[innerEnd - 1] {
+          trailing.insert(string, at: 0)
+          innerEnd -= 1
+        }
+        let inner = emit(pieces, in: innerStart..<innerEnd, closeForOpen: closeForOpen, depth: depth + 1)
+        let containsWhitespace = inner.contains { markup in
+          markup.plainText.contains { $0.isWhitespace }
+        }
+        output.append(contentsOf: leading.map { Text($0) })
+        if spec.allowsInnerWhitespace || !containsWhitespace {
+          output.append(InlineAttributes(attributes: "{\(spec.attribute):true}", recurring(inner)))
+        } else {
+          output.append(Text(spec.marker))
+          output.append(contentsOf: inner)
+          output.append(Text(spec.marker))
+        }
+        output.append(contentsOf: trailing.map { Text($0) })
+        index = close + 1
+      }
+    }
+    return output
+  }
+
+  /// `InlineAttributes` children must be `RecurringInlineMarkup`; other
+  /// nodes (`Link`, `Image`, a nested `InlineAttributes`) degrade to their
+  /// plain text.
+  private func recurring(_ inner: [InlineMarkup]) -> [any RecurringInlineMarkup] {
+    inner.map { $0 as? (any RecurringInlineMarkup) ?? Text($0.plainText) }
+  }
+
+  private func firstCharacter(of piece: Piece) -> Character? {
+    switch piece {
+    case .text(let string), .remainder(let string):
+      return string.first
+    case .node(let node):
+      return node.plainText.first
+    case .marker(let specIndex, _, _):
+      return specs[specIndex].marker.first
+    }
+  }
+
+  private func lastCharacter(of piece: Piece) -> Character? {
+    switch piece {
+    case .text(let string), .remainder(let string):
+      return string.last
+    case .node(let node):
+      return node.plainText.last
+    case .marker(let specIndex, _, _):
+      return specs[specIndex].marker.last
+    }
+  }
+}
diff --git a/Sources/MarkdownText/Parser/Scanners/MarkupPostParsingRewriter.swift b/Sources/MarkdownText/Parser/Scanners/MarkupPostParsingRewriter.swift
index 7c9ece7e..e656bb8c 100644
--- a/Sources/MarkdownText/Parser/Scanners/MarkupPostParsingRewriter.swift
+++ b/Sources/MarkdownText/Parser/Scanners/MarkupPostParsingRewriter.swift
@@ -64,6 +64,21 @@ final class InlineHTMLMarkupPostParsingRewriter: MarkupPostParsingRewriter {
   }
 }
 
+/// Rewrites paired inline delimiter runs into `InlineAttributes` nodes. See
+/// `InlineDelimiterRewriter`. Runs unconditionally: it only touches subtrees
+/// with a `Text` node containing a spec marker and is not a speculative
+/// repair.
+final class InlineDelimiterMarkupPostParsingRewriter: MarkupPostParsingRewriter {
+
+  private static let specs: [InlineDelimiterRewriter.DelimiterSpec] = [.highlight]
+
+  func rewriteIfApplicable(document: Document) -> Document? {
+    guard InlineDelimiterRewriter.containsDelimiter(document, specs: Self.specs) else { return nil }
+    var rewriter = InlineDelimiterRewriter(specs: Self.specs)
+    return rewriter.visit(document) as? Document
+  }
+}
+
 /// Splits paragraphs that contain images into block-level image-only
 /// paragraphs. See `ImageBlockRewriter`.
 ///
diff --git a/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift b/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift
new file mode 100644
index 00000000..2431882b
--- /dev/null
+++ b/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift
@@ -0,0 +1,175 @@
+//
+//  Copyright (c) Microsoft Corporation. All rights reserved.
+//  Licensed under the MIT License. See LICENSE in the project root for license information.
+//
+
+@testable import SwiftStreamingMarkdown
+import Markdown
+import XCTest
+
+final class InlineDelimiterRewriterTests: XCTestCase {
+
+  private let parser = MarkdownParserImpl()
+
+  /// Parses `text` through the full pipeline and returns the rendered
+  /// paragraph's attributed content.
+  private func renderedParagraph(_ text: String) async -> NSMutableAttributedString? {
+    let renderables = await renderables(text)
+    guard case .paragraph(_, let content) = renderables.first else { return nil }
+    return content
+  }
+
+  private func renderables(_ text: String) async -> [MarkdownRenderable] {
+    await parser.parse(text: text, config: .default).renderables
+  }
+
+  private func background(at index: Int, in content: NSMutableAttributedString?) -> MDColor? {
+    content?.attribute(.backgroundColor, at: index, effectiveRange: nil) as? MDColor
+  }
+
+  // MARK: - Pairing
+
+  func test_simple_highlight() async {
+    let content = await renderedParagraph("a ==b== c")
+    XCTAssertEqual(content?.string, "a b c")
+    XCTAssertNotNil(background(at: 2, in: content))
+    XCTAssertNil(background(at: 0, in: content))
+    XCTAssertNil(background(at: 4, in: content))
+  }
+
+  func test_highlight_whole_paragraph() async {
+    let content = await renderedParagraph("==x==")
+    XCTAssertEqual(content?.string, "x")
+    XCTAssertNotNil(background(at: 0, in: content))
+  }
+
+  func test_intraword_highlight() async {
+    let content = await renderedParagraph("a==b==c")
+    XCTAssertEqual(content?.string, "abc")
+    XCTAssertNotNil(background(at: 1, in: content))
+    XCTAssertNil(background(at: 0, in: content))
+    XCTAssertNil(background(at: 2, in: content))
+  }
+
+  func test_marker_touching_spaces_stays_literal() async {
+    let content = await renderedParagraph("== x ==")
+    XCTAssertEqual(content?.string, "== x ==")
+  }
+
+  func test_intraword_marker_touching_spaces_stays_literal() async {
+    let content = await renderedParagraph("x == y ==")
+    XCTAssertEqual(content?.string, "x == y ==")
+  }
+
+  func test_close_marker_preceded_by_space_stays_literal() async {
+    let content = await renderedParagraph("==x ==")
+    XCTAssertEqual(content?.string, "==x ==")
+  }
+
+  func test_open_marker_followed_by_space_stays_literal() async {
+    let content = await renderedParagraph("== x==")
+    XCTAssertEqual(content?.string, "== x==")
+  }
+
+  func test_unclosed_marker_stays_literal() async {
+    let content = await renderedParagraph("a ==b")
+    XCTAssertEqual(content?.string, "a ==b")
+  }
+
+  func test_odd_run_leaves_one_literal_equals() async {
+    let content = await renderedParagraph("===x===")
+    XCTAssertEqual(content?.string, "=x=")
+    XCTAssertNil(background(at: 0, in: content))
+    XCTAssertNotNil(background(at: 1, in: content))
+    XCTAssertNil(background(at: 2, in: content))
+  }
+
+  func test_double_run_nests_and_highlights() async {
+    let content = await renderedParagraph("====x====")
+    XCTAssertEqual(content?.string, "x")
+    XCTAssertNotNil(background(at: 0, in: content))
+  }
+
+  func test_nested_highlight_is_absorbed() async {
+    let content = await renderedParagraph("==a ==b== c==")
+    XCTAssertEqual(content?.string, "a b c")
+    for index in 0..<5 {
+      XCTAssertNotNil(background(at: index, in: content), "expected highlight at \(index)")
+    }
+  }
+
+  func test_highlight_wraps_strong() async {
+    let content = await renderedParagraph("a ==**b**== c")
+    XCTAssertEqual(content?.string, "a b c")
+    XCTAssertNotNil(background(at: 2, in: content))
+    let boldFont = content?.attribute(.font, at: 2, effectiveRange: nil) as? MDFont
+    let plainFont = content?.attribute(.font, at: 0, effectiveRange: nil) as? MDFont
+    XCTAssertNotNil(boldFont)
+    XCTAssertNotEqual(boldFont, plainFont)
+  }
+
+  func test_strong_wraps_highlight() async {
+    let content = await renderedParagraph("a **==b==** c")
+    XCTAssertEqual(content?.string, "a b c")
+    XCTAssertNotNil(background(at: 2, in: content))
+    let boldFont = content?.attribute(.font, at: 2, effectiveRange: nil) as? MDFont
+    let plainFont = content?.attribute(.font, at: 0, effectiveRange: nil) as? MDFont
+    XCTAssertNotNil(boldFont)
+    XCTAssertNotEqual(boldFont, plainFont)
+  }
+
+  func test_highlight_wraps_html_strong() async {
+    let content = await renderedParagraph("==a <b>b</b> c==")
+    XCTAssertEqual(content?.string, "a b c")
+    for index in 0..<5 {
+      XCTAssertNotNil(background(at: index, in: content), "expected highlight at \(index)")
+    }
+    let boldFont = content?.attribute(.font, at: 2, effectiveRange: nil) as? MDFont
+    let plainFont = content?.attribute(.font, at: 0, effectiveRange: nil) as? MDFont
+    XCTAssertNotNil(boldFont)
+    XCTAssertNotEqual(boldFont, plainFont)
+  }
+
+  // MARK: - Constrained containers and code spans
+
+  func test_marker_inside_link_text_stays_literal() async {
+    let content = await renderedParagraph("[==x==](https://ex.com)")
+    XCTAssertEqual(content?.string, "==x==")
+    let link = content?.attribute(.link, at: 0, effectiveRange: nil) as? URL
+    XCTAssertEqual(link?.absoluteString, "https://ex.com")
+  }
+
+  func test_marker_inside_code_span_stays_literal() async {
+    let content = await renderedParagraph("`==x==`")
+    XCTAssertEqual(content?.string, "==x==")
+  }
+
+  // MARK: - Other blocks
+
+  func test_highlight_in_heading() async {
+    let renderables = await renderables("# ==x==")
+    guard case .heading(_, let level, let content) = renderables.first else {
+      return XCTFail("expected heading")
+    }
+    XCTAssertEqual(level, 1)
+    XCTAssertEqual(content.string, "x")
+    XCTAssertNotNil(content.attribute(.backgroundColor, at: 0, effectiveRange: nil) as? MDColor)
+  }
+
+  func test_highlight_in_table_cell() async {
+    let renderables = await renderables("| head |\n| --- |\n| ==x== |")
+    guard case .table(_, _, let rows, _) = renderables.first else {
+      return XCTFail("expected table")
+    }
+    let cell = rows.first?.first
+    XCTAssertEqual(cell?.string, "x")
+    XCTAssertNotNil(cell?.attribute(.backgroundColor, at: 0, effectiveRange: nil) as? MDColor)
+  }
+
+  // MARK: - Non-regression
+
+  func test_document_without_markers_is_untouched() async {
+    let document = await parser.parse(text: "plain **bold** text")
+    XCTAssertEqual(document.debugDescription(), Document(parsing: "plain **bold** text").debugDescription())
+  }
+}

From caa0e43906786fa0f1007f600b4421d3b93e348c Mon Sep 17 00:00:00 2001
From: Vincent Peng <mail@vincentpeng.me>
Date: Fri, 9 Oct 2026 01:15:53 +1100
Subject: [PATCH 5/8] Compose nested InlineAttributes instead of dropping inner
 style
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A nested InlineAttributes child is not RecurringInlineMarkup, so the
first version degraded it to plain text and lost the inner style — e.g.
'==a <sup>b</sup>==' highlighted everything but dropped the
superscript. attributeWrap now splits the run around nested attribute
nodes and re-wraps each under the union of both key sets.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../Rewriters/InlineDelimiterRewriter.swift   | 65 +++++++++++++++++--
 .../InlineDelimiterRewriterTests.swift        | 14 ++++
 2 files changed, 73 insertions(+), 6 deletions(-)

diff --git a/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift b/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift
index 041fcdd3..2a08a832 100644
--- a/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift
+++ b/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift
@@ -255,7 +255,7 @@ final class InlineDelimiterRewriter: MarkupRewriter {
         }
         output.append(contentsOf: leading.map { Text($0) })
         if spec.allowsInnerWhitespace || !containsWhitespace {
-          output.append(InlineAttributes(attributes: "{\(spec.attribute):true}", recurring(inner)))
+          output.append(contentsOf: attributeWrap("\(spec.attribute):true", inner))
         } else {
           output.append(Text(spec.marker))
           output.append(contentsOf: inner)
@@ -268,11 +268,64 @@ final class InlineDelimiterRewriter: MarkupRewriter {
     return output
   }
 
-  /// `InlineAttributes` children must be `RecurringInlineMarkup`; other
-  /// nodes (`Link`, `Image`, a nested `InlineAttributes`) degrade to their
-  /// plain text.
-  private func recurring(_ inner: [InlineMarkup]) -> [any RecurringInlineMarkup] {
-    inner.map { $0 as? (any RecurringInlineMarkup) ?? Text($0.plainText) }
+  /// `InlineAttributes` children must be `RecurringInlineMarkup`, so a
+  /// generated wrap cannot contain a nested `InlineAttributes` node. Runs
+  /// around nested attribute nodes are split instead: each nested node's
+  /// children are re-wrapped under the union of both key sets, which keeps
+  /// e.g. `==a <sup>b</sup>==` as highlighted text with a superscripted `b`
+  /// rather than dropping the inner style. Other non-recurring children
+  /// (`Link`, `Image`) degrade to their plain text inside the current run.
+  private func attributeWrap(_ key: String, _ inner: [InlineMarkup]) -> [InlineMarkup] {
+    var output: [InlineMarkup] = []
+    var run: [any RecurringInlineMarkup] = []
+
+    func flushRun() {
+      guard !run.isEmpty else { return }
+      output.append(InlineAttributes(attributes: "{\(key)}", run))
+      run = []
+    }
+
+    for markup in inner {
+      if let attributes = markup as? InlineAttributes {
+        flushRun()
+        if let mergedKey = mergedKeys(key, inner: attributes.attributes) {
+          output.append(contentsOf: attributeWrap(mergedKey, attributes.children.compactMap { $0 as? InlineMarkup }))
+        } else {
+          output.append(attributes)
+        }
+      } else if let recurring = markup as? (any RecurringInlineMarkup) {
+        run.append(recurring)
+      } else {
+        run.append(Text(markup.plainText))
+      }
+    }
+    flushRun()
+    return output
+  }
+
+  /// Keys like `subscript:true` the renderer understands. Attribute nodes
+  /// generated by this rewriter and `InlineHTMLRewriter` always match;
+  /// anything else keeps its original attributes.
+  private static let enabledKeyRegex = try? Regex(#"(?:^|[,{}\s])([a-zA-Z]+)\s*:\s*true\b"#)
+
+  /// Union of `base` and the inner node's keys (`"a:true"` comma-separated
+  /// contents without braces). Returns `nil` when the inner attribute string
+  /// holds no recognized keys, so the node can pass through unchanged.
+  private func mergedKeys(_ base: String, inner: String) -> String? {
+    guard let regex = Self.enabledKeyRegex else { return nil }
+    var merged = base
+    var found = false
+    for match in inner.matches(of: regex) {
+      guard let key = match.output[1].substring else { continue }
+      let entry = "\(key):true"
+      // `{` or `,` boundary avoids prefix false-positives like `sub:` inside
+      // `subscript:`.
+      if !merged.contains("{\(entry)") && !merged.contains(",\(entry)") {
+        merged += ",\(entry)"
+      }
+      found = true
+    }
+    return found ? merged : nil
   }
 
   private func firstCharacter(of piece: Piece) -> Character? {
diff --git a/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift b/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift
index 2431882b..e441e054 100644
--- a/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift
+++ b/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift
@@ -27,6 +27,10 @@ final class InlineDelimiterRewriterTests: XCTestCase {
     content?.attribute(.backgroundColor, at: index, effectiveRange: nil) as? MDColor
   }
 
+  private func baseline(at index: Int, in content: NSMutableAttributedString?) -> CGFloat {
+    CGFloat((content?.attribute(.baselineOffset, at: index, effectiveRange: nil) as? NSNumber)?.doubleValue ?? 0)
+  }
+
   // MARK: - Pairing
 
   func test_simple_highlight() async {
@@ -130,6 +134,16 @@ final class InlineDelimiterRewriterTests: XCTestCase {
     XCTAssertNotEqual(boldFont, plainFont)
   }
 
+  func test_nested_attribute_nodes_compose() async {
+    let content = await renderedParagraph("==a <sup>b</sup> c==")
+    XCTAssertEqual(content?.string, "a b c")
+    for index in 0..<5 {
+      XCTAssertNotNil(background(at: index, in: content), "expected highlight at \(index)")
+    }
+    XCTAssertGreaterThan(baseline(at: 2, in: content), 0)
+    XCTAssertEqual(baseline(at: 0, in: content), 0)
+  }
+
   // MARK: - Constrained containers and code spans
 
   func test_marker_inside_link_text_stays_literal() async {

From 4b8a559c94c4a622a0a6b3e565d9c32deefb2457 Mon Sep 17 00:00:00 2001
From: Vincent Peng <mail@vincentpeng.me>
Date: Fri, 9 Oct 2026 01:33:47 +1100
Subject: [PATCH 6/8] Harden delimiter pairing from review findings

- Bound a marker's close index by the enclosing emit range so cross-spec
  pairs can't consume pieces the outer level emits again.
- Empty-inner pairs (a====b) emit literal markers instead of vanishing.
- attributeWrap keeps Link/Image nodes alive between styled runs instead
  of degrading them to plain text.
- Skip the inner whitespace scan for specs that allow it; dedupe merged
  attribute keys on exact entries.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../Rewriters/InlineDelimiterRewriter.swift   | 34 ++++++++++++++-----
 .../InlineDelimiterRewriterTests.swift        | 25 ++++++++++++++
 2 files changed, 51 insertions(+), 8 deletions(-)

diff --git a/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift b/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift
index 2a08a832..c31d4f46 100644
--- a/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift
+++ b/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift
@@ -229,7 +229,12 @@ final class InlineDelimiterRewriter: MarkupRewriter {
         index += 1
       case .marker(let specIndex, _, _):
         let spec = specs[specIndex]
-        guard let close = closeForOpen[index], depth < Self.maxDepth else {
+        // `close < range.upperBound` keeps cross-spec pairs from escaping
+        // the enclosing wrap's range: per-spec opener stacks can produce a
+        // pair whose closer lies outside an inner emit, which would emit
+        // the enclosing pieces twice. Crossing markers stay literal and the
+        // outer pair wins.
+        guard let close = closeForOpen[index], close < range.upperBound, depth < Self.maxDepth else {
           output.append(Text(spec.marker))
           index += 1
           continue
@@ -250,7 +255,17 @@ final class InlineDelimiterRewriter: MarkupRewriter {
           innerEnd -= 1
         }
         let inner = emit(pieces, in: innerStart..<innerEnd, closeForOpen: closeForOpen, depth: depth + 1)
-        let containsWhitespace = inner.contains { markup in
+        // An empty inner range (`a====b`) means the markers delimit nothing;
+        // emit them literally so the `=`s are not swallowed.
+        guard !inner.isEmpty else {
+          output.append(contentsOf: leading.map { Text($0) })
+          output.append(Text(spec.marker))
+          output.append(Text(spec.marker))
+          output.append(contentsOf: trailing.map { Text($0) })
+          index = close + 1
+          continue
+        }
+        let containsWhitespace = !spec.allowsInnerWhitespace && inner.contains { markup in
           markup.plainText.contains { $0.isWhitespace }
         }
         output.append(contentsOf: leading.map { Text($0) })
@@ -273,8 +288,8 @@ final class InlineDelimiterRewriter: MarkupRewriter {
   /// around nested attribute nodes are split instead: each nested node's
   /// children are re-wrapped under the union of both key sets, which keeps
   /// e.g. `==a <sup>b</sup>==` as highlighted text with a superscripted `b`
-  /// rather than dropping the inner style. Other non-recurring children
-  /// (`Link`, `Image`) degrade to their plain text inside the current run.
+  /// rather than dropping the inner style. `Link` and `Image` children end
+  /// the current run and pass through unstyled but alive.
   private func attributeWrap(_ key: String, _ inner: [InlineMarkup]) -> [InlineMarkup] {
     var output: [InlineMarkup] = []
     var run: [any RecurringInlineMarkup] = []
@@ -296,7 +311,12 @@ final class InlineDelimiterRewriter: MarkupRewriter {
       } else if let recurring = markup as? (any RecurringInlineMarkup) {
         run.append(recurring)
       } else {
-        run.append(Text(markup.plainText))
+        // `Link` and `Image` stay in the output between styled runs rather
+        // than degrading to text: `==a [x](u) b==` keeps a live link and
+        // `==a ![i](s) b==` keeps the image paragraph-visible for
+        // `ImageBlockRewriter`.
+        flushRun()
+        output.append(markup)
       }
     }
     flushRun()
@@ -318,9 +338,7 @@ final class InlineDelimiterRewriter: MarkupRewriter {
     for match in inner.matches(of: regex) {
       guard let key = match.output[1].substring else { continue }
       let entry = "\(key):true"
-      // `{` or `,` boundary avoids prefix false-positives like `sub:` inside
-      // `subscript:`.
-      if !merged.contains("{\(entry)") && !merged.contains(",\(entry)") {
+      if !merged.split(separator: ",").map(String.init).contains(entry) {
         merged += ",\(entry)"
       }
       found = true
diff --git a/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift b/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift
index e441e054..8855e56e 100644
--- a/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift
+++ b/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift
@@ -134,6 +134,31 @@ final class InlineDelimiterRewriterTests: XCTestCase {
     XCTAssertNotEqual(boldFont, plainFont)
   }
 
+  func test_empty_pair_stays_literal() async {
+    let content = await renderedParagraph("a====b")
+    XCTAssertEqual(content?.string, "a====b")
+  }
+
+  func test_highlight_preserves_link() async {
+    let content = await renderedParagraph("==a [x](https://ex.com) b==")
+    XCTAssertEqual(content?.string, "a x b")
+    let link = content?.attribute(.link, at: 2, effectiveRange: nil) as? URL
+    XCTAssertEqual(link?.absoluteString, "https://ex.com")
+    XCTAssertNotNil(background(at: 0, in: content))
+    XCTAssertNotNil(background(at: 4, in: content))
+  }
+
+  func test_highlight_preserves_paragraph_level_image() async {
+    let renderables = await parser.parse(
+      text: "==a ![alt](https://ex.com/i.png) b==",
+      config: .default.withImageConfig(ImageConfig(enabled: true, allowedImageTypes: [.remote(allowedDomains: [])]))
+    ).renderables
+    XCTAssertTrue(renderables.contains { renderable in
+      if case .image = renderable { return true }
+      return false
+    })
+  }
+
   func test_nested_attribute_nodes_compose() async {
     let content = await renderedParagraph("==a <sup>b</sup> c==")
     XCTAssertEqual(content?.string, "a b c")

From 03d6f03ca4134bbb4699428c62d1a9197e85bd53 Mon Sep 17 00:00:00 2001
From: Vincent Peng <mail@vincentpeng.me>
Date: Fri, 9 Oct 2026 01:59:24 +1100
Subject: [PATCH 7/8] Match markdown-it flanking, jump, and literal-fallback
 ordering

- applyFlanking now uses the full left/right-flanking rules (punctuation
  on either side of a run), so a==(b)==c and x==hi!==y stay literal and
  x==a)==b== picks the same pair the reference renderer does.
- pairedCloses skips an immediately adjacent opener, mirroring
  markdown-it's jump rule; ====x==== nests instead of each run's markers
  collapsing onto each other.
- emit's boundary-remainder strip now only hoists remainders matching
  the spec's own marker char, and the empty/rejected literal paths emit
  in piece order instead of reordering remainders across the markers.
- Corrected the stale doc comment: backslash-escaped \== stays literal
  because cmark emits the escape as a separate Text node.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../Rewriters/InlineDelimiterRewriter.swift   | 69 ++++++++++++++-----
 .../InlineDelimiterRewriterTests.swift        | 20 ++++++
 2 files changed, 72 insertions(+), 17 deletions(-)

diff --git a/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift b/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift
index c31d4f46..29d54178 100644
--- a/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift
+++ b/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift
@@ -25,10 +25,9 @@ import Markdown
 /// paired at their own level: their children must stay
 /// `RecurringInlineMarkup`, so `==` there remains literal.
 ///
-/// Known limitation: a backslash-escaped `\==` arrives as a literal `=` in
-/// `Text` content because cmark strips the escape during parsing, so
-/// `\==x==` still highlights. The two forms are indistinguishable at this
-/// layer.
+/// A backslash-escaped `\==` arrives as its own `Text` node because cmark
+/// emits escaped characters separately, so `\==x==` stays literal — the
+/// escape works.
 final class InlineDelimiterRewriter: MarkupRewriter {
 
   /// Describes one inline delimiter pair and the attribute it produces.
@@ -183,11 +182,24 @@ final class InlineDelimiterRewriter: MarkupRewriter {
         runEnd += 1
       }
       var runStart = index
-      while runStart > 0, case .remainder = pieces[runStart - 1] {
+      guard case .marker(let runSpecIndex, _, _) = pieces[index] else {
+        index += 1
+        continue
+      }
+      while runStart > 0, case .remainder(let string) = pieces[runStart - 1],
+            specs[runSpecIndex].marker.contains(string) {
         runStart -= 1
       }
-      let canClose = runStart > 0 && lastCharacter(of: pieces[runStart - 1])?.isWhitespace == false
-      let canOpen = runEnd < pieces.count && firstCharacter(of: pieces[runEnd])?.isWhitespace == false
+      let previous = runStart > 0 ? lastCharacter(of: pieces[runStart - 1]) : nil
+      let next = runEnd < pieces.count ? firstCharacter(of: pieces[runEnd]) : nil
+      let lastWS = previous?.isWhitespace ?? false
+      let lastPunct = previous.map(Self.isDelimiterPunctuation) ?? false
+      let nextWS = next?.isWhitespace ?? false
+      let nextPunct = next.map(Self.isDelimiterPunctuation) ?? false
+      // markdown-it's left/right-flanking rules; checking whitespace alone
+      // would pair `a==(b)==c`, which the reference renderer keeps literal.
+      let canClose = !lastWS && (!lastPunct || nextWS || nextPunct)
+      let canOpen = !nextWS && (!nextPunct || lastWS || lastPunct)
       for markerIndex in index..<runEnd {
         guard case .marker(let specIndex, _, _) = pieces[markerIndex] else { continue }
         pieces[markerIndex] = .marker(specIndex: specIndex, canOpen: canOpen, canClose: canClose)
@@ -198,13 +210,17 @@ final class InlineDelimiterRewriter: MarkupRewriter {
 
   /// Pairs each closer with the most recent unmatched opener of the same
   /// spec and returns `open index -> close index`. A marker that can both
-  /// open and close prefers closing when an opener exists.
+  /// open and close prefers closing when an opener exists, except an
+  /// immediately adjacent one: markdown-it's jump rule keeps `====x====`
+  /// pairing outer-to-inner instead of collapsing each run's two markers
+  /// onto each other with nothing between them.
   private func pairedCloses(in pieces: [Piece]) -> [Int: Int] {
     var openers: [[Int]] = specs.map { _ in [] }
     var closeForOpen: [Int: Int] = [:]
     for (index, piece) in pieces.enumerated() {
       guard case .marker(let specIndex, let canOpen, let canClose) = piece else { continue }
-      if canClose, let openIndex = openers[specIndex].popLast() {
+      if canClose, let openIndex = openers[specIndex].last, index - openIndex > 1 {
+        openers[specIndex].removeLast()
         closeForOpen[openIndex] = index
       } else if canOpen {
         openers[specIndex].append(index)
@@ -241,42 +257,50 @@ final class InlineDelimiterRewriter: MarkupRewriter {
         }
         // `remainder` pieces at the wrap boundary belong to the consumed
         // markers' own runs, so they emit outside: `===x===` highlights `x`
-        // and leaves one literal `=` on each side.
+        // and leaves one literal `=` on each side. A remainder whose char
+        // differs from the spec's marker is foreign interior content and
+        // stays inside the range (`=^` remainders never belong to a `^`
+        // run, which can't produce remainders at all).
         var innerStart = index + 1
         var innerEnd = close
         var leading: [String] = []
-        while innerStart < innerEnd, case .remainder(let string) = pieces[innerStart] {
+        while innerStart < innerEnd, case .remainder(let string) = pieces[innerStart],
+              spec.marker.contains(string) {
           leading.append(string)
           innerStart += 1
         }
         var trailing: [String] = []
-        while innerEnd > innerStart, case .remainder(let string) = pieces[innerEnd - 1] {
+        while innerEnd > innerStart, case .remainder(let string) = pieces[innerEnd - 1],
+              spec.marker.contains(string) {
           trailing.insert(string, at: 0)
           innerEnd -= 1
         }
         let inner = emit(pieces, in: innerStart..<innerEnd, closeForOpen: closeForOpen, depth: depth + 1)
         // An empty inner range (`a====b`) means the markers delimit nothing;
-        // emit them literally so the `=`s are not swallowed.
+        // emit in piece order so nothing is lost or reordered.
         guard !inner.isEmpty else {
-          output.append(contentsOf: leading.map { Text($0) })
-          output.append(Text(spec.marker))
           output.append(Text(spec.marker))
+          output.append(contentsOf: leading.map { Text($0) })
           output.append(contentsOf: trailing.map { Text($0) })
+          output.append(Text(spec.marker))
           index = close + 1
           continue
         }
         let containsWhitespace = !spec.allowsInnerWhitespace && inner.contains { markup in
           markup.plainText.contains { $0.isWhitespace }
         }
-        output.append(contentsOf: leading.map { Text($0) })
         if spec.allowsInnerWhitespace || !containsWhitespace {
+          output.append(contentsOf: leading.map { Text($0) })
           output.append(contentsOf: attributeWrap("\(spec.attribute):true", inner))
+          output.append(contentsOf: trailing.map { Text($0) })
         } else {
+          // Rejected pairs emit literally in piece order.
           output.append(Text(spec.marker))
+          output.append(contentsOf: leading.map { Text($0) })
           output.append(contentsOf: inner)
+          output.append(contentsOf: trailing.map { Text($0) })
           output.append(Text(spec.marker))
         }
-        output.append(contentsOf: trailing.map { Text($0) })
         index = close + 1
       }
     }
@@ -346,6 +370,17 @@ final class InlineDelimiterRewriter: MarkupRewriter {
     return found ? merged : nil
   }
 
+  /// ASCII punctuation matching markdown-it's `isPunctChar`
+  /// (`Character.isPunctuation` misses symbols like `` ` ``, `~`, `^`, `=`,
+  /// and `$`, which markdown-it counts as flanking punctuation).
+  private static let punctuationCharacters = Set<Character>(
+    "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"
+  )
+
+  private static func isDelimiterPunctuation(_ character: Character) -> Bool {
+    punctuationCharacters.contains(character)
+  }
+
   private func firstCharacter(of piece: Piece) -> Character? {
     switch piece {
     case .text(let string), .remainder(let string):
diff --git a/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift b/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift
index 8855e56e..cb2e9817 100644
--- a/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift
+++ b/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift
@@ -139,6 +139,26 @@ final class InlineDelimiterRewriterTests: XCTestCase {
     XCTAssertEqual(content?.string, "a====b")
   }
 
+  func test_punctuation_boundary_blocks_open() async {
+    // markdown-it flanking: `(` punct after `==` next to alnum `a` can't open.
+    let content = await renderedParagraph("a==(b)==c")
+    XCTAssertEqual(content?.string, "a==(b)==c")
+  }
+
+  func test_punctuation_boundary_blocks_close() async {
+    let content = await renderedParagraph("x==hi!==y")
+    XCTAssertEqual(content?.string, "x==hi!==y")
+  }
+
+  func test_punctuation_picks_the_right_pair() async {
+    // `==` after `)` can't close; the trailing `==` pairs with the
+    // post-`)` opener instead, matching markdown-it's pair choice.
+    let content = await renderedParagraph("x==a)==b==")
+    XCTAssertEqual(content?.string, "x==a)b")
+    XCTAssertNotNil(background(at: 5, in: content))
+    XCTAssertNil(background(at: 0, in: content))
+  }
+
   func test_highlight_preserves_link() async {
     let content = await renderedParagraph("==a [x](https://ex.com) b==")
     XCTAssertEqual(content?.string, "a x b")

From 246effef9ff1817ce39755bf1b7f87b4039e2ec8 Mon Sep 17 00:00:00 2001
From: Vincent Peng <mail@vincentpeng.me>
Date: Fri, 9 Oct 2026 03:01:54 +1100
Subject: [PATCH 8/8] Degrade non-hoistable nodes to text inside delimiter
 wraps
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ImageBlockRewriter can only hoist a paragraph-level Image. An Image or
SymbolLink inside a wrapped range deeper in (e.g. inside **==..==**)
would be silently dropped at conversion — degrade it to its text
fallback so the alt text joins the styled run instead of vanishing.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../Rewriters/InlineDelimiterRewriter.swift   | 50 ++++++++++++-------
 .../InlineDelimiterRewriterTests.swift        |  7 +++
 2 files changed, 40 insertions(+), 17 deletions(-)

diff --git a/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift b/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift
index 29d54178..ffce4450 100644
--- a/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift
+++ b/Sources/MarkdownText/Parser/Rewriters/InlineDelimiterRewriter.swift
@@ -91,7 +91,7 @@ final class InlineDelimiterRewriter: MarkupRewriter {
     if visited is Link || visited is Image || visited is InlineAttributes {
       return visited
     }
-    visited.setInlineChildren(process(Array(visited.children)))
+    visited.setInlineChildren(process(Array(visited.children), allowsImagePassthrough: visited is Paragraph))
     return visited
   }
 
@@ -106,16 +106,20 @@ final class InlineDelimiterRewriter: MarkupRewriter {
     }
   }
 
-  /// Pairs the container's direct children. When no marker pair exists the
-  /// input passes through unchanged so untouched subtrees keep identity.
-  private func process(_ input: [Markup]) -> [InlineMarkup] {
+  /// Pairs the container's direct children. `allowsImagePassthrough` is
+  /// true only at paragraph level, where `ImageBlockRewriter` can hoist a
+  /// paragraph-level `Image` out of a wrap; deeper containers would drop
+  /// the node at conversion. When no marker pair exists the input passes
+  /// through unchanged so untouched subtrees keep identity.
+  private func process(_ input: [Markup], allowsImagePassthrough: Bool) -> [InlineMarkup] {
     var pieces = tokenize(input)
     applyFlanking(&pieces)
     let closeForOpen = pairedCloses(in: pieces)
     guard !closeForOpen.isEmpty else {
       return input.compactMap { $0 as? InlineMarkup }
     }
-    return emit(pieces, in: 0..<pieces.count, closeForOpen: closeForOpen, depth: 0)
+    return emit(pieces, in: 0..<pieces.count, closeForOpen: closeForOpen, depth: 0,
+                allowsImagePassthrough: allowsImagePassthrough)
   }
 
   /// Splits sibling inline nodes into pieces. `Text` runs of a marker
@@ -232,7 +236,8 @@ final class InlineDelimiterRewriter: MarkupRewriter {
   /// Emits the piece range, wrapping each paired open/close span in an
   /// `InlineAttributes` node. Pairs nest, so an outer wrap absorbs an inner
   /// `InlineAttributes` as plain text; unpaired markers become literal text.
-  private func emit(_ pieces: [Piece], in range: Range<Int>, closeForOpen: [Int: Int], depth: Int) -> [InlineMarkup] {
+  private func emit(_ pieces: [Piece], in range: Range<Int>, closeForOpen: [Int: Int], depth: Int,
+                    allowsImagePassthrough: Bool) -> [InlineMarkup] {
     var output: [InlineMarkup] = []
     var index = range.lowerBound
     while index < range.upperBound {
@@ -275,7 +280,8 @@ final class InlineDelimiterRewriter: MarkupRewriter {
           trailing.insert(string, at: 0)
           innerEnd -= 1
         }
-        let inner = emit(pieces, in: innerStart..<innerEnd, closeForOpen: closeForOpen, depth: depth + 1)
+        let inner = emit(pieces, in: innerStart..<innerEnd, closeForOpen: closeForOpen, depth: depth + 1,
+                         allowsImagePassthrough: allowsImagePassthrough)
         // An empty inner range (`a====b`) means the markers delimit nothing;
         // emit in piece order so nothing is lost or reordered.
         guard !inner.isEmpty else {
@@ -291,7 +297,8 @@ final class InlineDelimiterRewriter: MarkupRewriter {
         }
         if spec.allowsInnerWhitespace || !containsWhitespace {
           output.append(contentsOf: leading.map { Text($0) })
-          output.append(contentsOf: attributeWrap("\(spec.attribute):true", inner))
+          output.append(contentsOf: attributeWrap("\(spec.attribute):true", inner,
+                                                  allowsImagePassthrough: allowsImagePassthrough))
           output.append(contentsOf: trailing.map { Text($0) })
         } else {
           // Rejected pairs emit literally in piece order.
@@ -312,9 +319,13 @@ final class InlineDelimiterRewriter: MarkupRewriter {
   /// around nested attribute nodes are split instead: each nested node's
   /// children are re-wrapped under the union of both key sets, which keeps
   /// e.g. `==a <sup>b</sup>==` as highlighted text with a superscripted `b`
-  /// rather than dropping the inner style. `Link` and `Image` children end
-  /// the current run and pass through unstyled but alive.
-  private func attributeWrap(_ key: String, _ inner: [InlineMarkup]) -> [InlineMarkup] {
+  /// rather than dropping the inner style. `Link` and paragraph-level
+  /// `Image` children end the current run and pass through unstyled but
+  /// alive; other non-recurring nodes (`SymbolLink`, or `Image` inside a
+  /// deeper container that can't hoist it) degrade to their text fallback
+  /// so they join the styled run instead of vanishing at conversion.
+  private func attributeWrap(_ key: String, _ inner: [InlineMarkup],
+                             allowsImagePassthrough: Bool) -> [InlineMarkup] {
     var output: [InlineMarkup] = []
     var run: [any RecurringInlineMarkup] = []
 
@@ -328,19 +339,24 @@ final class InlineDelimiterRewriter: MarkupRewriter {
       if let attributes = markup as? InlineAttributes {
         flushRun()
         if let mergedKey = mergedKeys(key, inner: attributes.attributes) {
-          output.append(contentsOf: attributeWrap(mergedKey, attributes.children.compactMap { $0 as? InlineMarkup }))
+          output.append(contentsOf: attributeWrap(mergedKey, attributes.children.compactMap { $0 as? InlineMarkup },
+                                                  allowsImagePassthrough: allowsImagePassthrough))
         } else {
           output.append(attributes)
         }
       } else if let recurring = markup as? (any RecurringInlineMarkup) {
         run.append(recurring)
-      } else {
-        // `Link` and `Image` stay in the output between styled runs rather
-        // than degrading to text: `==a [x](u) b==` keeps a live link and
-        // `==a ![i](s) b==` keeps the image paragraph-visible for
-        // `ImageBlockRewriter`.
+      } else if markup is any InlineConvertible || (markup is Image && allowsImagePassthrough) {
+        // `Link` and other convertible nodes stay in the output between
+        // styled runs; a paragraph-level `Image` stays a node so
+        // `ImageBlockRewriter` can hoist it.
         flushRun()
         output.append(markup)
+      } else {
+        // An `Image` deeper than paragraph level or a `SymbolLink` would
+        // be silently dropped at conversion; degrade to its text fallback
+        // so `**==a ![i](s) b==**` keeps "i" inside the styled run.
+        run.append(Text(markup.plainText))
       }
     }
     flushRun()
diff --git a/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift b/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift
index cb2e9817..aee7398f 100644
--- a/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift
+++ b/Tests/MarkdownTextTests/InlineDelimiterRewriterTests.swift
@@ -168,6 +168,13 @@ final class InlineDelimiterRewriterTests: XCTestCase {
     XCTAssertNotNil(background(at: 4, in: content))
   }
 
+  func test_image_inside_emphasis_highlight_degrades_to_alt_text() async {
+    // Inside `**…**` an Image node would be dropped at conversion; the
+    // alt text joins the styled run instead.
+    let content = await renderedParagraph("**==a ![i](https://ex.com/i.png) b==**")
+    XCTAssertEqual(content?.string, "a i b")
+  }
+
   func test_highlight_preserves_paragraph_level_image() async {
     let renderables = await parser.parse(
       text: "==a ![alt](https://ex.com/i.png) b==",