From 9092ab3dbd74481ec1060fc9954234ccc1fc1452 Mon Sep 17 00:00:00 2001 From: Mihaela Mihaljevic Date: Tue, 9 Jun 2026 05:46:12 +0200 Subject: [PATCH] feat(html): adoption agency algorithm and active formatting elements (#83) --- CHANGELOG.md | 1 + README.md | 2 +- Sources/HTML/HTMLAdoptionAgency.swift | 156 +++++++++++++++++++++++++ Sources/HTML/HTMLDocumentBuilder.swift | 28 ++++- Tests/HTMLAdoptionTests.swift | 44 +++++++ 5 files changed, 224 insertions(+), 7 deletions(-) create mode 100644 Sources/HTML/HTMLAdoptionAgency.swift create mode 100644 Tests/HTMLAdoptionTests.swift diff --git a/CHANGELOG.md b/CHANGELOG.md index 12a056e..0cf9054 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- HTML5 adoption agency algorithm and active formatting elements (#83, stage 4): misnested formatting tags are now recovered exactly as the HTML standard prescribes. Overlapping tags nest (`` -> ``), content after an out-of-order close is re-wrapped by reconstructing the active formatting elements (`X` -> `X`), and a block inside a formatting element reparents through the furthest-block path, including the canonical `

12345

` -> `

12345

`. - HTML5 SVG element-name case adjustment (#83, stage 3): an SVG element written in mixed case (which the tokenizer lowercases) is restored to its canonical camel case in the tree, so ``, ``, ``, and the rest carry their correct SVG names. Applies only in the SVG namespace; same-named HTML elements keep their lowercased name. - HTML5 foreign content (#83, stage 2): an `` or `` element and all of its descendants now carry the SVG (`http://www.w3.org/2000/svg`) or MathML (`http://www.w3.org/1998/Math/MathML`) namespace on their `QualifiedName`, so foreign elements are distinguishable from same-named HTML; ordinary HTML content (including content after a closed ``) stays in no namespace. (SVG/MathML element- and attribute-name case adjustment, and HTML integration points, are a later refinement.) - HTML5 table tree construction (#83, stage 1): a `` written without its section and row wrappers now nests correctly. A `` directly inside a `
` gets an implied ``, a `` (and section), consecutive rows share one implied ``, and an explicit ``/``/`` is not duplicated, all inside an open table only. diff --git a/README.md b/README.md index 4ca1bde..f97218c 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ flowchart TB PureXML is a working, dependency-free XML library today: parse, emit, validate, query, and stream documents on macOS, Linux, Windows, and WASM. The test suite -currently runs **727 tests in 114 suites** (`swift test`). +currently runs **733 tests in 115 suites** (`swift test`). ### Shipped (libxml2-aligned surface) diff --git a/Sources/HTML/HTMLAdoptionAgency.swift b/Sources/HTML/HTMLAdoptionAgency.swift new file mode 100644 index 0000000..67612cb --- /dev/null +++ b/Sources/HTML/HTMLAdoptionAgency.swift @@ -0,0 +1,156 @@ +extension HTMLDocument { + /// The formatting elements tracked on the active-formatting list and recovered + /// by the adoption agency. + private static let formatting: Set = [ + "a", "b", "big", "code", "em", "font", "i", "nobr", "s", "small", "strike", "strong", "tt", "u", + ] + + /// The "special" category: an element of this kind, open below a formatting + /// element, is the furthest block that triggers reparenting. + private static let special: Set = [ + "address", "applet", "area", "article", "aside", "blockquote", "body", "br", "button", "caption", + "center", "col", "colgroup", "dd", "details", "dir", "div", "dl", "dt", "embed", "fieldset", + "figcaption", "figure", "footer", "form", "frame", "frameset", "h1", "h2", "h3", "h4", "h5", "h6", + "header", "hgroup", "hr", "html", "iframe", "img", "input", "li", "listing", "main", "marquee", + "menu", "nav", "object", "ol", "p", "plaintext", "pre", "section", "select", "summary", "table", + "tbody", "td", "textarea", "tfoot", "th", "thead", "title", "tr", "ul", "wbr", "xmp", + ] + + /// The elements that bound "element in scope" lookups. + private static let scopeBoundaries: Set = [ + "applet", "caption", "html", "table", "td", "th", "marquee", "object", + ] + + func isFormatting(_ name: String) -> Bool { + Self.formatting.contains(name) + } + + private func openIndex(_ node: PureXML.Model.TreeNode) -> Int? { + openBody.firstIndex { $0 === node } + } + + private func formattingIndex(_ node: PureXML.Model.TreeNode) -> Int? { + activeFormatting.firstIndex { $0 === node } + } + + /// Whether `target` is in scope: reachable up the open stack without crossing a + /// scope boundary. + private func hasInScope(_ target: PureXML.Model.TreeNode) -> Bool { + for node in openBody.reversed() { + if node === target { return true } + if Self.scopeBoundaries.contains(tagName(node)) { return false } + } + return false + } + + /// The HTML5 "reconstruct the active formatting elements" step: re-open any + /// formatting elements that were closed out of order, so content after them is + /// re-wrapped (the `X` -> `X` behavior). + func reconstructActiveFormatting() { + guard var index = activeFormatting.indices.last else { return } + if activeFormatting[index] == nil || isOpen(activeFormatting[index]) { return } + while index > 0 { + index -= 1 + if activeFormatting[index] == nil || isOpen(activeFormatting[index]) { + index += 1 + break + } + } + while index < activeFormatting.count { + if let template = activeFormatting[index] { + let clone = template.shallowCopy() + openBody.last?.append(clone) + openBody.append(clone) + activeFormatting[index] = clone + } + index += 1 + } + } + + private func isOpen(_ node: PureXML.Model.TreeNode?) -> Bool { + guard let node else { return false } + return openBody.contains { $0 === node } + } + + /// The HTML5 adoption agency algorithm: recovers a misnested formatting element + /// end tag, reparenting the intervening block (the "furthest block") and + /// cloning the formatting element around it. + func adoptionAgency(_ subject: String) { + if let current = openBody.last, current !== bodyRoot, tagName(current) == subject, formattingIndex(current) == nil { + openBody.removeLast() + return + } + var outer = 0 + while outer < 8 { + outer += 1 + guard let formattingIndexInList = lastFormatting(tag: subject), let formattingElement = activeFormatting[formattingIndexInList] else { + bodyClose(subject) + return + } + guard let formattingOpenIndex = openIndex(formattingElement) else { + activeFormatting.remove(at: formattingIndexInList) + return + } + if !hasInScope(formattingElement) { return } + guard let furthestBlockIndex = openBody[(formattingOpenIndex + 1)...].firstIndex(where: { Self.special.contains(tagName($0)) }) else { + openBody.removeLast(openBody.count - formattingOpenIndex) + activeFormatting.remove(at: formattingIndexInList) + return + } + reparent(formattingElement: formattingElement, formattingIndexInList: formattingIndexInList, furthestBlockIndex: furthestBlockIndex) + } + } + + private func lastFormatting(tag: String) -> Int? { + for index in activeFormatting.indices.reversed() { + guard let entry = activeFormatting[index] else { return nil } // a marker bounds the search + if tagName(entry) == tag { return index } + } + return nil + } + + /// Steps 8-19 of the algorithm: walk the open elements between the formatting + /// element and the furthest block, cloning formatting nodes, then clone the + /// formatting element around the furthest block's content. + private func reparent(formattingElement: PureXML.Model.TreeNode, formattingIndexInList: Int, furthestBlockIndex: Int) { + let furthestBlock = openBody[furthestBlockIndex] + guard let formattingOpenIndex = openIndex(formattingElement), formattingOpenIndex >= 1 else { return } + let commonAncestor = openBody[formattingOpenIndex - 1] + var bookmark = formattingIndexInList + var lastNode = furthestBlock + var nodeIndex = furthestBlockIndex + var inner = 0 + while inner < 3 { + inner += 1 + nodeIndex -= 1 + let node = openBody[nodeIndex] + if node === formattingElement { break } + guard let activeIndex = formattingIndex(node) else { + openBody.remove(at: nodeIndex) + continue + } + let clone = node.shallowCopy() + activeFormatting[activeIndex] = clone + openBody[nodeIndex] = clone + if lastNode === furthestBlock { bookmark = activeIndex + 1 } + clone.append(lastNode) + lastNode = clone + } + commonAncestor.append(lastNode) + let formattingClone = formattingElement.shallowCopy() + for child in furthestBlock.children { + formattingClone.append(child) + } + furthestBlock.append(formattingClone) + if let removeIndex = formattingIndex(formattingElement) { + activeFormatting.remove(at: removeIndex) + if removeIndex < bookmark { bookmark -= 1 } + } + activeFormatting.insert(formattingClone, at: min(bookmark, activeFormatting.count)) + if let removeOpen = openIndex(formattingElement) { openBody.remove(at: removeOpen) } + // The clone becomes a child of the furthest block, so it sits immediately + // above it on the open-elements stack; inserting below would re-find the + // same furthest block and loop. + if let blockIndex = openIndex(furthestBlock) { openBody.insert(formattingClone, at: blockIndex + 1) } + } +} diff --git a/Sources/HTML/HTMLDocumentBuilder.swift b/Sources/HTML/HTMLDocumentBuilder.swift index f6d6c01..5aff056 100644 --- a/Sources/HTML/HTMLDocumentBuilder.swift +++ b/Sources/HTML/HTMLDocumentBuilder.swift @@ -28,8 +28,9 @@ private enum InsertionMode { /// Builds a full HTML document from tokens by driving the HTML5 insertion modes, /// materializing the implied `html`/`head`/`body` and routing head-only elements -/// into the head. File-scope and private. -private final class HTMLDocument { +/// into the head. The adoption agency lives in a sibling file, so this type is +/// internal (its members stay private except the live-body state it shares). +final class HTMLDocument { typealias Token = PureXML.HTML.Token typealias Node = PureXML.Model.Node typealias Attribute = PureXML.Model.Attribute @@ -50,8 +51,11 @@ private final class HTMLDocument { /// of currently-open elements into that tree, with the body element at the /// bottom. This lets the adoption agency reparent already-built subtrees, which /// a pop-on-close model cannot. - private let bodyRoot = PureXML.Model.TreeNode.element("body") - private lazy var openBody: [PureXML.Model.TreeNode] = [bodyRoot] + let bodyRoot = PureXML.Model.TreeNode.element("body") + lazy var openBody: [PureXML.Model.TreeNode] = [bodyRoot] + /// The active formatting elements (the HTML5 list), with nil entries acting as + /// scope markers. Drives reconstruction and the adoption agency. + var activeFormatting: [PureXML.Model.TreeNode?] = [] func build(_ tokens: [Token]) -> Node { for token in tokens { @@ -159,10 +163,15 @@ private final class HTMLDocument { private func processInBody(_ token: Token) { switch token { case let .startTag(name, attributes, selfClosing): + reconstructActiveFormatting() bodyOpen(name, attributes, selfClosing: selfClosing) + noteOpenedFormatting(name, selfClosing: selfClosing) + case let .endTag(name) where isFormatting(name): + adoptionAgency(name) case let .endTag(name) where name != "body" && name != "html": bodyClose(name) case let .text(value): + reconstructActiveFormatting() bodyInsert(.text(value)) case let .comment(value): bodyInsert(.comment(value)) @@ -171,11 +180,18 @@ private final class HTMLDocument { } } + /// After opening a start tag, records it on the active-formatting list when it + /// is a formatting element (so misnesting can be recovered later). + private func noteOpenedFormatting(_ name: String, selfClosing: Bool) { + guard isFormatting(name), !selfClosing, !PureXML.HTML.Elements.void.contains(name), let opened = openBody.last else { return } + activeFormatting.append(opened) + } + // MARK: Body building (live mutable tree) /// The lowercased tag name of an open element, for case-insensitive stack /// matching (an SVG element's canonical camel case folds back to the token). - private func tagName(_ node: PureXML.Model.TreeNode) -> String { + func tagName(_ node: PureXML.Model.TreeNode) -> String { node.name?.localName.lowercased() ?? "" } @@ -194,7 +210,7 @@ private final class HTMLDocument { } } - private func bodyClose(_ name: String) { + func bodyClose(_ name: String) { guard let index = openBody.lastIndex(where: { tagName($0) == name }), index >= 1 else { return } openBody.removeLast(openBody.count - index) } diff --git a/Tests/HTMLAdoptionTests.swift b/Tests/HTMLAdoptionTests.swift new file mode 100644 index 0000000..1ca1ce5 --- /dev/null +++ b/Tests/HTMLAdoptionTests.swift @@ -0,0 +1,44 @@ +@testable import PureXML +import Testing + +@Suite("HTML5 adoption agency (misnested formatting elements)") +struct HTMLAdoptionTests { + private func body(_ html: String) -> String { + let full = PureXML.HTML.serialize(PureXML.HTML.parseDocument(html)) + let wrapper = "" + guard full.hasPrefix(wrapper), full.hasSuffix("") else { return full } + return String(full.dropFirst(wrapper.count).dropLast("".count)) + } + + @Test("Overlapping formatting tags are nested") + func test_overlapping() { + #expect(body("") == "") + } + + @Test("Content after a misnested close is re-wrapped (reconstruction)") + func test_reconstruction() { + #expect(body("X") == "X") + } + + @Test("A block inside a formatting element triggers the furthest-block path") + func test_furthestBlock() { + #expect(body("1

23

") == "1

23

") + } + + @Test("Nested anchors and formatting close cleanly") + func test_nestedFormatting() { + #expect(body("") == "") + } + + @Test("The canonical adoption-agency example reparents correctly") + func test_canonicalExample() { + // The well-known html5lib case for the adoption agency algorithm. + #expect(body("

12345

") == "

12345

") + } + + @Test("Well-nested formatting is unchanged") + func test_wellNested() { + #expect(body("x") == "x") + #expect(body("

bold and italic

") == "

bold and italic

") + } +}
`/`` gets an implied `